現行標準 — 最終更新日 2024年8月15日
a要素
em要素
strong要素
small要素
s要素
cite要素
q要素
dfn要素
abbr要素
ruby要素
rt要素
rp要素
data要素
time要素
code要素
var要素
samp要素
kbd要素
subおよびsup要素
i要素
b要素
u要素
mark要素
bdi要素
bdo要素
span要素
br要素
wbr要素
a要素およびarea要素によって作成されたリンク
a要素およびarea要素のAPI
alternate"
author"
bookmark"
canonical"
dns-prefetch"
expect"
external"
help"
icon"
license"
manifest"
modulepreload"
nofollow"
noopener"
noreferrer"
opener"
pingback"
preconnect"
prefetch"
preload"
privacy-policy"
search"
stylesheet"
tag"
terms-of-service"
picture要素
source要素
img要素
source、img、link要素に共通する属性
iframe要素
embed要素
object要素
video要素
audio要素
track要素
TrackEventインターフェイス
map要素
area要素
form要素
label要素
input要素
type属性の状態
type=hidden)
type=text)状態および検索状態
(type=search)
type=tel)
type=url)
type=email)
type=password)
type=date)
type=month)
type=week)
type=time)
type=datetime-local)
type=number)
type=range)
type=color)
type=checkbox)
type=radio)
type=file)
type=submit)
type=image)
type=reset)
type=button)
input要素属性
input要素API
button要素
select要素
datalist要素
optgroup要素
option要素
textarea要素
output要素
progress要素
meter要素
fieldset要素
legend要素
script要素
noscript要素
template要素
slot要素
canvas要素
Path2Dオブジェクト
ImageBitmapレンダリングコンテキスト
OffscreenCanvasインターフェイス
canvas要素のセキュリティ
Window,
WindowProxy, Locationオブジェクトのセキュリティインフラストラクチャ
Windowオブジェクト
WindowProxyエキゾチックオブジェクト
Locationインターフェース
Historyインターフェース
NotRestoredReasonsインターフェース
X-Frame-Optionsヘッダー
Refreshヘッダー
WindowOrWorkerGlobalScopeミックスイン
button 要素
details および summary 要素
input 要素
input 要素
input 要素
input 要素
input 要素
input 要素
input 要素
marquee 要素
meter 要素
progress
要素
select 要素
textarea
要素
この仕様は、ウェブプラットフォームの大部分を非常に詳細に定義しています。他の仕様と比較した場合のこの仕様の位置付けは、以下のようにまとめることができます:
このセクションは規範的ではありません。
簡単に言えば: はい。
もう少し詳しく言うと、「HTML5」という用語は、現代のウェブ技術を指す流行語として広く使われています。その多く(すべてではありませんが)はWHATWGで開発されています。このドキュメントもその一つです。他のドキュメントはWHATWG標準概要から入手できます。
このセクションは規範的ではありません。
HTMLはワールドワイドウェブのコアマークアップ言語です。元々、HTMLは科学文書を意味的に記述するための言語として主に設計されました。しかし、その一般的な設計により、後年には他の種類の文書やアプリケーションを記述するために適応されてきました。
このセクションは規範的ではありません。
この仕様は、この仕様で定義された機能を使用する文書やスクリプトの作成者、ページ上でこの仕様で定義された機能を操作するツールの実装者、およびこの仕様の要件に対して文書や実装の正確性を確認しようとする人々を対象としています。
このドキュメントは、ウェブ技術に対して少なくとも最低限の知識を持っていない読者には、適していない可能性があります。なぜなら、ところどころで正確さのために明確さを犠牲にし、完全さのために簡潔さを犠牲にしているからです。より分かりやすいチュートリアルや作成ガイドが、このトピックへのより優しい導入を提供してくれます。
特に、DOMの基本的な理解が、この仕様の技術的な部分を完全に理解するために必要です。また、Web IDL、HTTP、XML、Unicode、文字エンコーディング、JavaScript、およびCSSの理解も役立ちますが、必須ではありません。
このセクションは規範的ではありません。
この仕様は、静的な文書から動的なアプリケーションまで、ウェブ上でアクセシブルなページを作成するためのセマンティックレベルのマークアップ言語と、それに関連するセマンティックレベルのスクリプトAPIを提供することに限定されています。
この仕様の範囲には、メディア固有のプレゼンテーションのカスタマイズを提供するためのメカニズムは含まれていません(ただし、ウェブブラウザーのデフォルトのレンダリングルールはこの仕様の末尾に含まれており、言語の一部としてCSSにフックするためのいくつかのメカニズムが提供されています)。
この仕様の範囲は、オペレーティングシステム全体を記述することではありません。特に、ハードウェア構成ソフトウェア、画像操作ツール、およびユーザーが高性能ワークステーションで日常的に使用すると予想されるアプリケーションは範囲外です。アプリケーションに関しては、この仕様は特に、ユーザーがたまに使用する、または異なる場所から定期的に使用することが予想される、低いCPU要件のアプリケーションを対象としています。このようなアプリケーションの例としては、オンライン購入システム、検索システム、ゲーム(特にマルチプレイヤーオンラインゲーム)、公共の電話帳や住所録、通信ソフトウェア(メールクライアント、インスタントメッセージクライアント、ディスカッションソフトウェア)、文書編集ソフトウェアなどがあります。
このセクションは規範的ではありません。
HTMLは、最初の5年間(1990-1995年)に数回の改訂を経て、多くの拡張を経験し、主に最初はCERN、次にIETFでホストされました。
W3Cの設立に伴い、HTMLの開発は再び場所を変更しました。1995年にHTML 3.0として知られるHTMLの拡張に関する最初の失敗した試みは、1997年に完成したHTML 3.2として知られるより実用的なアプローチに道を譲りました。その同じ年にHTML4が迅速に続きました。
翌年、W3CのメンバーはHTMLの進化を停止し、代わりにXMLベースの同等物であるXHTMLの開発を開始することを決定しました。この努力は、2000年に完成した、HTML4のXMLでの再定式化であるXHTML 1.0として知られるものから始まりました。新しいシリアル化を追加した以外に新機能はなく、その後、W3Cの焦点はXHTMLを拡張しやすくすることに向けられました。XHTML Modularizationの旗印の下で、この取り組みは行われました。これと並行して、W3Cは以前のHTMLおよびXHTML言語と互換性のない新しい言語にも取り組み、それをXHTML2と呼びました。
1998年にHTMLの進化が停止されたころ、ブラウザーベンダーによって開発されたHTMLのAPIの一部が指定され、DOM Level 1(1998年)およびDOM Level 2 CoreとDOM Level 2 HTML(2000年に開始され、2003年に最高潮に達しました)という名前で公開されました。これらの努力はその後縮小し、2004年にDOM Level 3の一部の仕様が公開されましたが、すべてのLevel 3ドラフトが完成する前に作業グループは閉鎖されました。
2003年には、ウェブフォームの次世代として位置付けられたXFormsの公開が、HTML自体の進化に対する新たな関心を呼び起こしました。これは、既存の技術(例えばHTML)を置き換えるのではなく、まったく新しい技術(RSSや後のAtomなど)に限定されているという認識から生まれました。
HTML4のフォームを拡張して、XForms 1.0が導入した多くの機能を、既存のHTMLウェブページと互換性のないレンダリングエンジンをブラウザーが実装する必要なしに提供できることを示す概念実証が、この新たな関心の最初の成果でした。この初期段階では、草案はすでに公開されており、すべてのソースからの意見が求められていましたが、仕様はオペラソフトウェアの著作権の下にのみありました。
HTMLの進化を再開すべきという考えは、2004年のW3Cワークショップで試され、HTML5の作業の基礎を成すいくつかの原則(以下に記述)および前述のフォーム関連機能に関する初期の草案提案が、MozillaとOperaによってW3Cに共同で提示されました。提案は、ウェブの進化のために以前に選ばれた方向と矛盾するという理由で拒否されました。W3Cのスタッフとメンバーは、代わりにXMLベースの代替品を開発し続けることに投票しました。
その直後、Apple、Mozilla、Operaは、WHATWGという新しい場の下でこの取り組みを続ける意向を共同で発表しました。公開のメーリングリストが作成され、草案はWHATWGのサイトに移されました。著作権はその後、3社の共同所有に改訂され、仕様の再利用が可能になりました。
WHATWGは、特に技術が後方互換性を持つ必要があること、仕様と実装が一致する必要があること(たとえそれが実装ではなく仕様を変更することを意味する場合でも)、および仕様が非常に詳細である必要があることといういくつかの基本原則に基づいていました。これにより、実装が互いにリバースエンジニアリングすることなく完全な相互運用性を実現できるようにする必要がありました。
特に後者の要件により、HTML5仕様の範囲には、以前は3つの別々の文書で指定されていたHTML4、XHTML1、およびDOM2 HTMLが含まれる必要がありました。また、これまでに考えられていたよりもはるかに多くの詳細を含める必要がありました。
2006年にW3Cは最終的にHTML5の開発に参加する意向を示し、2007年には、WHATWGと協力してHTML5仕様の開発に取り組む作業グループが設立されました。Apple、Mozilla、Operaは、仕様をW3Cの著作権の下で公開することを許可し、同時にWHATWGサイトにより制約の少ないライセンスを持つバージョンを保持しました。
数年間、両グループは協力して作業を続けました。しかし、2011年には、両グループは異なる目標を持っているとの結論に達しました。W3Cは「完成」バージョンの「HTML5」を公開したいと考え、WHATWGはプラットフォームの進化に合わせて必要に応じて新機能を追加し、既知の問題を抱えた状態で仕様を固定するのではなく、仕様を継続的に維持するリビングスタンダードとしてHTMLの作業を続けたいと考えました。
2019年、WHATWGとW3Cは、今後HTMLの単一バージョンを共同で開発することに合意しました。これがこの文書です。
このセクションは規範的ではありません。
HTMLの多くの側面は、一見すると無意味で一貫性がないように見えることを認めざるを得ません。
HTML、そのサポートとなるDOM API、およびその多くのサポート技術は、数十年にわたって、異なる優先事項を持つさまざまな人々によって開発されてきましたが、多くの場合、彼らはお互いの存在を知らなかったのです。
そのため、機能は多くのソースから生まれ、一貫して設計されていないことがしばしばあります。さらに、ウェブのユニークな特性により、実装のバグが事実上、そして今では法的に標準となっていることがよくあります。なぜなら、コンテンツが意図せずにそれらに依存して書かれることが多く、修正が行われる前にそうなってしまうからです。
それにもかかわらず、特定の設計目標に従うための努力がなされてきました。これらは次のいくつかのサブセクションで説明されています。
このセクションは規範的ではありません。
ウェブ作成者がマルチスレッドの複雑さにさらされないようにするために、HTMLおよびDOM APIは、スクリプトが他のスクリプトの同時実行を検出できないように設計されています。ワーカーを使用しても、すべてのグローバルでのすべてのスクリプトの実行を完全にシリアライズするかのように実装の動作を考えることが意図されています。
この一般的な設計原則の例外は、JavaScriptのSharedArrayBuffer
クラスです。SharedArrayBuffer
オブジェクトを使用すると、他のエージェントでスクリプトが同時に実行されていることが実際に観察できます。さらに、JavaScriptのメモリモデルのため、シリアライズされたスクリプト実行によってだけでなく、シリアライズされたステートメント実行によっても表現できない状況があります。
このセクションは規範的ではありません。
この仕様は、さまざまな他の仕様と相互作用し、それらに依存しています。残念ながら、特定の状況では、相反するニーズにより、この仕様が他の仕様の要件に違反することがありました。これが発生した場合は、その違反は「意図的違反」としてそれぞれ記録され、その違反の理由が記載されています。
このセクションは規範的ではありません。
HTMLには、安全にセマンティクスを追加するために使用できるさまざまな拡張メカニズムがあります:
作成者は、class属性を使用して要素を拡張し、最も適切な既存の「実際の」HTML要素を使用しながら、独自の要素を効果的に作成できます。拡張を知らないブラウザや他のツールでも、ある程度サポートされるようにするためです。例えば、これはマイクロフォーマットで使用されています。
作成者は、data-*=""属性を使用して、インラインのクライアントサイドスクリプトやサーバーサイドのサイト全体のスクリプトが処理するためのデータを含めることができます。これらはブラウザによって変更されることはなく、スクリプトがHTML要素上にデータを含め、その後スクリプトがそれを検索して処理することができます。
作成者は、<meta name="" content="">メカニズムを使用して、ページ全体のメタデータを含めることができます。
作成者は、rel=""メカニズムを使用して、リンクに特定の意味を注釈付けし、リンクタイプの事前定義セットに対する拡張を登録することで拡張することができます。これもマイクロフォーマットで使用されています。
作成者は、カスタムタイプを使用して、<script type="">メカニズムを使用して生データを埋め込み、その後、インラインまたはサーバーサイドのスクリプトで処理します。
作成者は、JavaScriptのプロトタイプ機構を使用してAPIを拡張できます。これは、スクリプトライブラリによって広く使用されています。
作成者は、マイクロデータ機能(itemscope=""およびitemprop=""属性)を使用して、他のアプリケーションやサイトと共有するためのネストされた名前と値のペアのデータを埋め込むことができます。
作成者は、HTMLの語彙を拡張するためにカスタム要素を定義、共有、および使用することができます。有効なカスタム要素名の要件は、将来ハイフンを含むローカル名を持つ要素がHTML、SVG、またはMathMLに追加されないことを保証します。
このセクションは規範的ではありません。
この仕様は、文書やアプリケーションを記述するための抽象言語と、この言語を使用するリソースのメモリ内表現と対話するためのいくつかのAPIを定義しています。
メモリ内表現は「DOM HTML」、または略して「DOM」として知られています。
この抽象言語を使用するリソースを送信するために使用できるさまざまな具体的な構文があり、そのうちの2つはこの仕様で定義されています。
最初の具体的な構文はHTML構文です。これはほとんどの作成者に推奨される形式です。ほとんどのレガシーウェブブラウザと互換性があります。ドキュメントがtext/html MIMEタイプで送信される場合、それはウェブブラウザによってHTMLドキュメントとして処理されます。この仕様は単に「HTML」として知られる最新のHTML構文を定義しています。
2番目の具体的な構文はXMLです。ドキュメントがapplication/xhtml+xmlのようなXML
MIMEタイプで送信される場合、それはウェブブラウザによってXMLドキュメントとして扱われ、XMLプロセッサによって解析されます。作成者は、XMLとHTMLの処理が異なることを念頭に置いてください。特に、些細な構文エラーでも、XMLとしてラベル付けされたドキュメントが完全にレンダリングされるのを防ぐ可能性がありますが、HTML構文では無視されます。
HTMLのXML構文はかつて「XHTML」と呼ばれていましたが、この仕様ではその用語を使用していません(他の理由として、MathMLやSVGのHTML構文にはそのような用語が使用されていないためです)。
DOM、HTML構文、およびXML構文は、すべて同じコンテンツを表現することはできません。例えば、名前空間はHTML構文では表現できませんが、DOMやXML構文ではサポートされています。同様に、noscript機能を使用するドキュメントは、HTML構文で表現できますが、DOMやXML構文では表現できません。文字列「-->」を含むコメントは、HTMLおよびXML構文ではなく、DOMでのみ表現できます。
このセクションは規範的ではありません。
この仕様は以下の主要なセクションに分かれています:
EventSource)や、スクリプト用の双方向フルデュプレックスソケットプロトコルであるWeb
Socketsについても紹介しています。
また、いくつかの付録があり、廃止された機能やIANAの考慮事項をリストアップしており、いくつかの索引も含まれています。
この仕様は他のすべての仕様と同様に読むべきです。まず、最初から最後まで何度も読みます。そして、少なくとも一度は逆順に読みます。次に、内容一覧からランダムにセクションを選び、すべての相互参照をたどりながら読みます。
以下の適合要件セクションに記載されているように、この仕様はさまざまな適合クラスのための適合基準を説明しています。特に、プロデューサー(例:著者や彼らが作成する文書)に適用される適合要件と、コンシューマー(例:ウェブブラウザー)に適用される適合要件があります。これらは、何を要求しているかによって区別できます:プロデューサーに対する要件は許可されるものを述べており、コンシューマーに対する要件はソフトウェアがどのように動作すべきかを述べています。
例えば、「foo属性の値は有効な整数でなければならない」というのはプロデューサーに対する要件です。なぜなら、それが許可される値を規定しているからです。一方で、「foo属性の値は整数を解析するためのルールを使用して解析されなければならない」というのはコンシューマーに対する要件です。なぜなら、それがコンテンツをどのように処理するかを記述しているからです。
プロデューサーに対する要件は、コンシューマーに対してはまったく影響を与えません。
上記の例を続けると、特定の属性の値が有効な整数に制約されるという要件は、コンシューマーに対する要件について何も意味しないことを強調しておきます。実際には、コンシューマーがその属性を不透明な文字列として扱うことが要求されているかもしれません。その場合、値が要件に準拠しているかどうかにはまったく影響されません。あるいは、コンシューマーが無効な(この場合は非数値の)値をどのように処理するかを定義する特定のルールを使用して値を解析することが求められているかもしれません。
これは定義、要件、または説明です。
これは注釈です。
これは例です。
これは未解決の問題です。
これは警告です。
[Exposed =Window ]
interface Example {
// this is an IDL definition
};
variable = object.method([optionalArgument])
これはインターフェースの使用法を説明する著者への注釈です。
/* this is a CSS fragment */
用語の定義インスタンスはこのようにマークアップされます。その用語の使用例はこのようにまたはこのようにマークアップされます。
要素、属性、またはAPIの定義インスタンスはこのようにマークアップされます。それらの要素、属性、またはAPIへの参照はこのようにマークアップされます。
その他のコード片はこのようにマークアップされます。
変数はこのようにマークアップされます。
アルゴリズムでは、同期セクション内のステップは⌛でマークされます。
場合によっては、条件とそれに対応する要件の形式で要件が提示されることがあります。このような場合、条件に適用される要件は、常にその条件に続く最初の要件セットです。これには、これらの要件に対して複数の条件セットがある場合でも該当します。そのようなケースは次のように提示されます:
このセクションは規範的ではありません。
基本的なHTMLドキュメントは次のようになります:
<!DOCTYPE html>
< html lang = "en" >
< head >
< title > Sample page</ title >
</ head >
< body >
< h1 > Sample page</ h1 >
< p > This is a < a href = "demo.html" > simple</ a > sample.</ p >
<!-- this is a comment -->
</ body >
</ html >
HTMLドキュメントは、要素とテキストのツリーで構成されています。各要素は、開始タグ(例えば「<body>」)と終了タグ(例えば「</body>」)でソース内に示されます。(特定の開始タグと終了タグは、特定のケースで省略され、他のタグによって暗黙的に示されます。)
タグは、要素が互いに完全に内包されるようにネストされ、重複しないようにする必要があります:
< p > This is < em > very < strong > wrong</ em > !</ strong ></ p >
< p > This < em > is < strong > correct</ strong > .</ em ></ p >
この仕様は、HTMLで使用できる一連の要素と、要素をネストする方法に関するルールを定義しています。
要素には、その動作を制御する属性を持たせることができます。以下の例では、a要素とそのhref属性を使用して作成されたハイパーリンクがあります:
< a href = "demo.html" > simple</ a >
属性は開始タグの内部に配置され、名前と値から成り、それらは「=」文字で区切られます。属性値に引用符がない場合、それが含まれていない場合は" ' ` =
<または>を含む場合を除き、ASCIIの空白文字は残したままにすることができます。それ以外の場合は、単一引用符または二重引用符のいずれかで引用する必要があります。値が空の文字列である場合は、値と「=」文字全体を省略することもできます。
<!-- empty attributes -->
< input name = address disabled >
< input name = address disabled = "" >
<!-- attributes with a value -->
< input name = address maxlength = 200 >
< input name = address maxlength = '200' >
< input name = address maxlength = "200" >
HTMLユーザーエージェント(例:ウェブブラウザ)は、このマークアップを解析し、それをDOM(Document Object Model)ツリーに変換します。DOMツリーは、ドキュメントのメモリ内表現です。
DOMツリーには、DocumentTypeノード、Elementノード、Textノード、Commentノード、場合によってはProcessingInstructionノードなど、さまざまな種類のノードが含まれます。
このセクションの上部にあるマークアップスニペットは、次のDOMツリーに変換されます:
このツリーのドキュメント要素は、HTMLドキュメントで常にその位置にあるhtml要素です。これには、head要素とbody要素、およびそれらの間にテキストノードが含まれています。
DOMツリーには、予想以上に多くのテキストノードが含まれています。これは、ソースに多数のスペース(ここでは「␣」で表される)と改行(「⏎」)が含まれており、これらがすべてDOMのテキストノードとして表示されるためです。ただし、歴史的な理由から、元のマークアップ内のすべてのスペースと改行がDOMに表示されるわけではありません。特に、head開始タグの前のすべての空白は静かに削除され、body終了タグの後のすべての空白は、bodyの最後に配置されます。
head要素には、title要素が含まれており、これは「Sample
page」というテキストを含むテキストノード自体を含んでいます。同様に、body要素には、h1要素、p要素、およびコメントが含まれています。
このDOMツリーは、ページ内のスクリプトから操作することができます。スクリプト(通常はJavaScript)は、script要素を使用して埋め込むか、イベントハンドラーのコンテンツ属性を使用して埋め込むことができる小さなプログラムです。例えば、フォームのoutput要素の値を「Hello
World」に設定するスクリプトを含むフォームは次のようになります:
< form name = "main" >
Result: < output name = "result" ></ output >
< script >
document. forms. main. elements. result. value = 'Hello World' ;
</ script >
</ form >
DOMツリー内の各要素はオブジェクトで表されており、これらのオブジェクトには操作できるようにするためのAPIがあります。例えば、リンク(上記のツリー内のa要素など)の「href」属性は、いくつかの方法で変更できます:
var a = document. links[ 0 ]; // ドキュメント内の最初のリンクを取得
a. href = 'sample.html' ; // リンク先のURLを変更
a. protocol = 'https' ; // URLのスキーム部分だけを変更
a. setAttribute( 'href' , 'https://example.com/' ); // 属性の内容を直接変更
DOMツリーは、HTMLドキュメントが実装によって処理および表示されるとき(特にウェブブラウザーのようなインタラクティブな実装の場合)に使用される表現方法であるため、この仕様は上記のマークアップよりも主にDOMツリーの観点で記述されています。
HTMLドキュメントは、インタラクティブなコンテンツを媒体に依存しない形で表現します。HTMLドキュメントは、画面に表示されたり、音声合成装置で読み上げられたり、点字ディスプレイに表示されたりすることがあります。これらのレンダリングがどのように行われるかを正確に制御するために、作成者はCSSのようなスタイリング言語を使用することができます。
次の例では、CSSを使用してページが黄色地に青色のテキストになっています。
<!DOCTYPE html>
< html lang = "en" >
< head >
< title > Sample styled page</ title >
< style >
body { background : navy ; color : yellow ; }
</ style >
</ head >
< body >
< h1 > Sample styled page</ h1 >
< p > This page is just a demo.</ p >
</ body >
</ html >
HTMLの使用方法についての詳細は、作成者にチュートリアルやガイドを参照することをお勧めします。この仕様に含まれているいくつかの例も役立つかもしれませんが、初心者の作成者には、この仕様が必要に応じて定義している言語の詳細レベルが最初は理解しにくいかもしれないことを注意しておきます。
このセクションは規範的ではありません。
HTMLを使用してインタラクティブなサイトを作成する場合、攻撃者がサイト自体やサイトのユーザーのセキュリティを侵害する脆弱性を導入しないよう注意が必要です。
この問題に関する包括的な研究はこのドキュメントの範囲外であり、作成者にはこの問題をより詳細に研究することを強くお勧めします。ただし、このセクションでは、HTMLアプリケーション開発における一般的な落とし穴について簡単に紹介します。
ウェブのセキュリティモデルは「オリジン」の概念に基づいており、それに対応してウェブ上の多くの潜在的な攻撃はオリジンをまたがるアクションに関連しています。[ORIGIN]
信頼できない入力、たとえばユーザー生成コンテンツ(テキストコメントなど)、URLパラメータ内の値、サードパーティサイトからのメッセージなどを受け入れる際には、使用する前にデータを検証し、表示する際には適切にエスケープすることが不可欠です。これを怠ると、悪意のあるユーザーがさまざまな攻撃を実行できるようになります。これには、偽のユーザー情報(負の年齢など)を提供するような比較的無害なものから、情報を含むページをユーザーが閲覧するたびにスクリプトを実行し、攻撃を拡散させるような深刻なもの、さらにはサーバー上のすべてのデータを削除するような壊滅的なものまで含まれます。
ユーザー入力を検証するためのフィルタを書く際には、必ずホワイトリストベースのフィルタを使用し、既知の安全な構文を許可し、それ以外のすべての入力を禁止する必要があります。ブラックリストベースのフィルタ(既知の悪意のある入力を禁止し、それ以外のすべてを許可する)は安全ではありません。なぜなら、悪意のあるものすべてがまだ知られているわけではないからです(たとえば、将来発明されるかもしれないものなど)。
たとえば、あるページが表示内容を決定するためにURLのクエリ文字列を参照し、次のようにユーザーをそのページにリダイレクトしてメッセージを表示するとします:
< ul >
< li >< a href = "message.cgi?say=Hello" > Say Hello</ a >
< li >< a href = "message.cgi?say=Welcome" > Say Welcome</ a >
< li >< a href = "message.cgi?say=Kittens" > Say Kittens</ a >
</ ul >
メッセージがエスケープされずにユーザーに表示された場合、悪意のある攻撃者がスクリプト要素を含むURLを作成することができます:
https://example.com/message.cgi?say=%3Cscript%3Ealert%28%27Oh%20no%21%27%29%3C/script%3E
攻撃者がこのページを訪問するよう被害者ユーザーを誘導すると、攻撃者が選んだスクリプトがページ上で実行されます。このようなスクリプトは、そのサイトが提供する機能に応じて、数多くの悪意のある操作を行う可能性があります。たとえば、そのサイトがeコマースショップである場合、そのようなスクリプトはユーザーに気づかれずに不要な購入を任意の回数行わせることができます。
これはクロスサイトスクリプティング攻撃と呼ばれます。
サイトにコードを実行させるためのトリックを試みるために使用できる構文は多数あります。以下に、作成者がホワイトリストフィルタを作成する際に考慮することが推奨されるいくつかの構文を示します:
imgのような無害に見える要素を許可する場合、提供される属性もホワイトリストに登録することが重要です。すべての属性を許可した場合、攻撃者はonload属性を使用して任意のスクリプトを実行することができます。
javascript:」ですが、ユーザーエージェントは他にも(実際に歴史的に)実装することがあります。
base要素の挿入を許可すると、ページ内のscript要素に相対リンクが含まれている場合、それらがハイジャックされる可能性があり、同様にフォーム送信も悪意のあるサイトにリダイレクトされる可能性があります。
サイトがユーザー固有の副作用を伴うフォーム送信を許可する場合(たとえば、ユーザーの名前でフォーラムにメッセージを投稿する、購入を行う、パスポートを申請するなど)、リクエストがユーザーによって意図的に行われたものであり、他のサイトがユーザーをだまして知らないうちにリクエストを行わせたものではないことを確認することが重要です。
この問題は、HTMLフォームが他のオリジンに送信される可能性があるために存在します。
サイトは、フォームにユーザー固有の隠しトークンを挿入するか、すべてのリクエストで`Origin`ヘッダーをチェックすることで、このような攻撃を防ぐことができます。
ユーザーにとって意図しない操作を行わせる可能性のあるインターフェースを提供するページは、ユーザーがインターフェースを誤って有効にしてしまう可能性を回避するように設計する必要があります。
ユーザーがこのようにだまされる方法の一つは、悪意のあるサイトが被害者のサイトを小さなiframeに配置し、ユーザーにリアクションゲームをさせるように説得する場合です。ユーザーがゲームをプレイしている間、悪意のあるサイトはiframeをマウスカーソルの下に素早く配置し、ユーザーがクリックしようとする瞬間に被害者サイトのインターフェースをクリックさせるようにします。
これを回避するために、フレーム内で使用されることを予期していないサイトは、フレーム内にないことを検出した場合にのみインターフェースを有効にすることが推奨されます(たとえば、windowオブジェクトをtop属性の値と比較するなど)。
このセクションは規範的ではありません。
HTMLのスクリプトには「実行完了まで実行する」という意味があります。つまり、ブラウザはスクリプトを中断せずに実行し、その後で他のイベントを発生させたり、ドキュメントの解析を続行したりします。
一方、HTMLファイルの解析はインクリメンタルに行われ、パーサーはスクリプトを実行するためにいつでも停止できます。これは通常、良いことですが、作成者はイベントハンドラーをイベントが発生する可能性がある前にフックしないよう注意する必要があります。
これを確実に行うための2つの技術があります:イベントハンドラーコンテンツ属性を使用するか、要素を作成し、同じスクリプト内でイベントハンドラーを追加する方法です。後者は安全です。前述したように、スクリプトは他のイベントが発生する前に完了するまで実行されるためです。
これが現れる一例は、img要素とloadイベントです。このイベントは、特に画像がすでにキャッシュされている場合(よくあることです)、要素が解析されるとすぐに発生する可能性があります。
ここで、作成者はonloadハンドラーを使用して、img要素にloadイベントをキャッチさせます:
< img src = "games.png" alt = "Games" onload = "gamesLogoHasLoaded(event)" >
要素がスクリプトによって追加されている場合、イベントハンドラーが同じスクリプト内で追加される限り、イベントが見逃されることはありません:
< script >
var img = new Image();
img. src = 'games.png' ;
img. alt = 'Games' ;
img. onload = gamesLogoHasLoaded;
// img.addEventListener('load', gamesLogoHasLoaded, false); // も機能します
</ script >
しかし、作成者が最初にimg要素を作成し、その後別のスクリプトでイベントリスナーを追加した場合、loadイベントがその間に発生し、見逃される可能性があります:
<!-- このスタイルは使わないでください、競合状態があります! -->
< img id = "games" src = "games.png" alt = "Games" >
<!-- パーサーが一時停止している間に'load'イベントが発生する可能性があります。 -->
< script >
var img = document. getElementById( 'games' );
img. onload = gamesLogoHasLoaded; // 発生しないかもしれません!
</ script >
このセクションは規範的ではありません。
作成者には、一般的なミスを発見するために適合チェッカー(バリデーターとも呼ばれます)を利用することを推奨します。WHATWGは以下のURLでそのようなツールのリストを提供しています:https://whatwg.org/validator/
このセクションは規範的ではありません。
以前のHTML仕様とは異なり、この仕様では無効なドキュメントと有効なドキュメントの処理がある程度詳しく定義されています。
ただし、無効なコンテンツの処理がほとんどの場合よく定義されているにもかかわらず、ドキュメントの適合要件は依然として重要です。実際には、相互運用性(すべての実装が特定のコンテンツを信頼できる、一貫したまたは同等の方法で処理する状況)がドキュメント適合要件の唯一の目標ではありません。このセクションでは、適合ドキュメントとエラードキュメントを区別する理由のいくつかを詳細に説明します。
このセクションは規範的ではありません。
以前のバージョンのHTMLに含まれていたほとんどの表示専用機能は、もはや許可されていません。一般的に、表示専用のマークアップには以下のような問題があることが判明しています:
表示専用のマークアップを使用して支援技術(AT)ユーザーにとって受け入れ可能な体験を提供することは可能ですが(例:ARIAの使用)、意味的に適切なマークアップを使用するよりもはるかに難しいです。さらに、そのような技術を使用しても、テキストモードブラウザのユーザーなど、非AT非グラフィカルユーザーに対してページをアクセシブルにすることはできません。
一方、媒体に依存しないマークアップを使用することで、より多くのユーザー(例:テキストブラウザのユーザー)に対応できるドキュメントを簡単に作成することができます。
スタイルに依存しない形で書かれたサイトは、メンテナンスがはるかに簡単です。たとえば、<font color="">を使用しているサイトの色を変更する場合、サイト全体で変更が必要ですが、CSSに基づくサイトの場合、単一のファイルを変更するだけで済みます。
表示専用のマークアップは冗長になりがちであり、その結果、ドキュメントサイズが大きくなります。
これらの理由から、このバージョンのHTMLでは表示専用のマークアップが削除されました。この変更は驚くべきことではありません。HTML4では何年も前に表示専用マークアップが非推奨とされ、作成者が表示専用マークアップから移行するのを支援するためのモード(HTML4 Transitional)が提供されました。その後、XHTML 1.1ではそれらの機能が完全に廃止されました。
HTMLに残されている唯一の表示専用のマークアップ機能は、style属性とstyle要素です。style属性の使用は、プロダクション環境ではあまり推奨されませんが、迅速なプロトタイピングに役立ちます(そのルールを後で別のスタイルシートに移動できるため)。また、別のスタイルシートが不便な場合には特定のスタイルを提供するために使用することができます。同様に、style要素は、シンジケーションやページ固有のスタイルに役立ちますが、一般的にはスタイルが複数のページに適用される場合、外部スタイルシートの方が便利です。
また、以前は表示専用とされていたいくつかの要素が、この仕様では媒体に依存しない形で再定義されていることにも注意が必要です:b、i、hr、s、small、およびu。
このセクションは規範的ではありません。
HTMLの構文は、さまざまな問題を回避するために制約されています。
特定の無効な構文構造は、解析されると非常に直感に反するDOMツリーを生成することがあります。
ユーザーエージェントが、より奇妙で複雑なエラーハンドリングルールを実装することなく制御された環境で使用できるようにするために、ユーザーエージェントは、解析エラーに遭遇した場合に失敗することが許されています。
特定のエラーハンドリングの挙動(たとえば、前述の<table><hr>...の例の挙動など)は、ストリーミングユーザーエージェント(HTMLファイルを状態を保持せずに一度のパスで処理するユーザーエージェント)と互換性がありません。そのようなユーザーエージェントとの互換性の問題を回避するために、そのような挙動を引き起こす構文は無効と見なされます。
XMLに基づくユーザーエージェントがHTMLパーサーに接続されている場合、HTMLファイルによってXMLが強制する特定の不変条件(たとえば、要素や属性の名前に複数のコロンが含まれることはない)が違反される可能性があります。これに対処するには、HTML DOMをXML互換のインフォセットに強制的に変換する必要がある場合があります。このような処理が必要なほとんどの構文構造は無効と見なされます。(連続する2つのハイフンを含むコメントや、ハイフンで終わるコメントは、HTML構文で許可される例外です。)
特定の構文構造は、非常にパフォーマンスが低下することがあります。そのような構文の使用を思いとどまらせるために、それらは通常非適合とされます。
たとえば、次のマークアップは、すべての未閉鎖のi要素が各段落で再構築されるため、パフォーマンスが低下し、各段落にますます多くの要素が追加されることになります:
< p >< i > She dreamt.
< p >< i > She dreamt that she ate breakfast.
< p >< i > Then lunch.
< p >< i > And finally dinner.
この断片に対応するDOMは次のようになります:
歴史的な理由から、比較的脆弱な構文構造があります。このような問題に偶然遭遇するユーザーの数を減らすために、それらは非適合とされています。
たとえば、属性内での特定の名前付き文字参照の解析は、閉じセミコロンが省略されていても行われます。アンパサンドと文字を続けて書くことは安全ですが、その文字が名前付き文字参照を構成する場合、その文字が意図せずにその文字として解釈される可能性があります。
この断片では、属性の値は「?bill&ted」です:
< a href = "?bill&ted" > Bill and Ted</ a >
しかし、次の断片では、属性の値は実際には「?art©」であり、意図していた「?art©」ではありません。これは、閉じセミコロンがなくても「©」が「©」と同じように処理され、「©」と解釈されるためです:
< a href = "?art©" > Art and Copy</ a >
この問題を回避するために、すべての名前付き文字参照はセミコロンで終わる必要があり、セミコロンなしで名前付き文字参照を使用することはエラーとしてフラグが立てられます。
したがって、上記のケースを表現する正しい方法は次のとおりです:
< a href = "?bill&ted" > Bill and Ted</ a > <!-- &tedは名前付き文字参照ではないので問題ありません -->
< a href = "?art&copy" > Art and Copy</ a > <!-- &がエスケープされている必要があります。なぜなら、©は名前付き文字参照だからです -->
特定の構文構造は、レガシーユーザーエージェントで特に微妙または重大な問題を引き起こすことが知られており、それらは非適合とされ、作成者がそれらを回避できるようにします。
たとえば、U+0060 GRAVE ACCENT文字(`)が引用符なしの属性で許可されていないのは、このためです。特定のレガシーユーザーエージェントでは、それが引用符文字として扱われることがあります。
特定の制約は、既知のセキュリティ問題を回避するためにのみ存在します。
たとえば、UTF-7の使用に関する制約は、UTF-7を使用した既知のクロスサイトスクリプティング攻撃から作成者が被害を受けないようにするためだけに存在します。[UTF7]
作成者の意図が非常に不明確なマークアップは、しばしば非適合とされます。これらのエラーを早期に修正することで、後のメンテナンスが容易になります。
ユーザーが単純な誤植をした場合、そのエラーが早期に検出されると便利です。これは、作成者のデバッグ時間を大幅に節約できます。このため、この仕様では、要素名や属性名などが仕様で定義された名前と一致しない場合、それをエラーと見なすことが多いです。
たとえば、作成者が<capton>と入力してしまった場合、これがエラーとしてフラグが立てられ、作成者はすぐに誤植を修正できます。
言語構文が将来拡張される可能性を考慮して、その他の点では無害な機能が禁止されています。
たとえば、終了タグ内の「属性」は現在無視されていますが、それらは無効です。これは、将来言語がその構文機能を使用する変更を行った場合でも、既に展開されている(かつ有効な!)コンテンツと競合しないようにするためです。
一部の作成者は、すべての属性を常に引用符で囲み、すべてのオプションのタグを常に含める習慣を持っていることが役立つと感じています。そのような作成者を支援するために、適合チェッカーはそのような慣行を強制する操作モードを提供することができます。
このセクションは規範的ではありません。
言語の構文に加えて、この仕様は要素や属性の指定方法に関する制限も課しています。これらの制限は、同様の理由で存在します:
定義された意味を持つ要素の誤用を避けるため、コンテンツモデルが定義されており、そのような入れ子が疑わしい価値を持つ場合には要素の入れ子を制限します。
たとえば、この仕様では、section
要素をkbd
要素内に入れ子にすることを禁止しています。なぜなら、作成者がセクション全体をキー入力することを意図している可能性が非常に低いためです。
同様に、要素の使用において作成者の誤りに注意を促すために、表現されたセマンティクスに明確な矛盾がある場合も適合エラーと見なされます。
たとえば、以下のフラグメントでは、セマンティクスが意味不明です。区切り線がセルであることや、ラジオボタンが進捗バーであることはありえません。
< hr role = "cell" >
< input type = radio role = progressbar >
もう一つの例として、ul
要素のコンテンツモデルに関する制限があります。これは、li
要素のみを子要素として許可します。リストとは定義上、0個以上のリスト項目から成るものであり、ul
要素がli
要素以外のものを含む場合、それが何を意味しているのかが明確ではありません。
特定の要素には、特定の組み合わせが混乱を招く可能性が高いデフォルトのスタイルや動作があります。これらの問題がない同等の代替手段がある場合、混乱を招く組み合わせは許可されていません。
たとえば、div
要素はブロックボックスとしてレンダリングされ、span
要素はインラインボックスとしてレンダリングされます。ブロックボックスを
インラインボックスに入れ子にするのは不必要に混乱を招きます。div
要素を入れ子にする、またはspan
要素を入れ子にする、あるいはspan
要素をdiv
要素の中に入れ子にすることで同じ目的を達成できますが、後者の方法のみがブロックボックスをインラインボックスに入れることを伴うため、この組み合わせは許可されていません。
別の例としては、インタラクティブコンテンツを入れ子にすることができない方法があります。たとえば、button
要素にtextarea
要素を含めることはできません。これは、そのような入れ子のデフォルトの動作がユーザーにとって非常に混乱を招くためです。これらの要素を入れ子にする代わりに、隣り合わせに配置することができます。
何かが許可されていないのは、それを許可すると作成者に混乱を招く可能性があるためです。
たとえば、disabled
属性を"false"に設定することは禁止されています。これは、見かけ上は要素が有効であることを意味しているように見えますが、実際には要素が無効であることを意味しているためです(実装にとって重要なのは属性の存在であり、その値ではありません)。
一部の適合エラーは、作成者が学ぶ必要がある言語を簡素化するために存在します。
たとえば、area
要素のshape
属性は、実際にはcirc
とcircle
値の両方を同義語として受け入れるにもかかわらず、circ
値の使用を禁止しています。これは、チュートリアルや他の学習支援ツールを簡素化するためです。両方を許可することにはメリットがなく、言語を教える際には混乱を招くだけです。
特定の要素は、いくつかの偏った方法でパースされます(主に歴史的な理由から)、それらのコンテンツモデルの制限は、作成者がこれらの問題に直面しないようにすることを目的としています。
たとえば、form
要素はフレージングコンテンツの中に入れることはできません。なぜなら、HTMLとしてパースされると、form
要素の開始タグがp
要素の終了タグを暗黙的に示すためです。したがって、次のマークアップは1つの段落ではなく、2つの段落を生成します:
< p > Welcome. < form >< label > Name:</ label > < input ></ form >
これは次のようにパースされます:
< p > Welcome. </ p >< form >< label > Name:</ label > < input ></ form >
一部のエラーは、デバッグが難しいスクリプトの問題を防ぐためのものです。
たとえば、同じ値を持つ2つのid
属性を持つことが適合しないとされるのは、重複するIDが間違った要素を選択する原因となり、場合によってはその原因を特定するのが困難な災害的な影響を引き起こすためです。
一部の構造は、歴史的に多くの作成者の時間を浪費してきたため、それを避けるように作成者を促すことで、将来の作業で時間を節約できるようにするために禁止されています。
たとえば、script
要素のsrc
属性が要素の内容を無視させることがあります。しかし、特に要素の内容が実行可能なスクリプトのように見える場合、これは明らかではなく、作成者がインラインスクリプトをデバッグしようとして多くの時間を費やすことになります。これを防ぐために、この仕様ではsrc
属性が存在する場合に、script
要素に実行可能なスクリプトが含まれている場合、それを適合しないとしています。これにより、ドキュメントを検証している作成者がこの種の誤りで時間を浪費する可能性が低くなります。
一部の作成者は、XMLとHTMLの両方として解釈され、同様の結果をもたらすファイルを作成することを好みます。この慣行は、スクリプト、スタイリング、または自動シリアル化のいかなる種類を含む場合、さまざまな微妙な問題が絡み合うため、一般的には推奨されませんが、この仕様には少なくともその困難をある程度緩和するためのいくつかの制限があります。これにより、作成者がHTMLとXMLの構文間を移行する際の一時的なステップとしてこれを使用しやすくなります。
たとえば、lang
属性とxml:lang
属性の値を同期させるための複雑なルールがあります。
もう一つの例として、HTMLシリアライゼーションにおけるxmlns属性の値に対する制限があります。これは、処理がHTMLまたはXMLとして行われた場合でも、適合するドキュメント内の要素が同じ名前空間に収まるようにするためです。
言語構文を将来のリビジョンで拡張できるようにするための制限と同様に、要素のコンテンツモデルや属性の値に対する制限の一部は、HTML語彙の将来の拡張を可能にするためのものです。
たとえば、target
属性の値をU+005F低線(_)文字で始まる特定の事前定義された値のみに制限することで、将来的に事前定義された新しい値を導入しても、作成者が定義した値と競合することがなくなります。
特定の制限は、他の仕様によって課された制限をサポートすることを目的としています。
たとえば、メディアクエリリストを取る属性に対して、有効なメディアクエリリストのみを使用することを要求することで、その仕様の適合ルールに従うことの重要性を強調しています。
このセクションは規範的ではありません。
この仕様書の読者にとって、以下の文書が興味深いかもしれません。
このアーキテクチャ仕様は、仕様書の著者、ソフトウェア開発者、およびコンテンツ開発者に、Unicode標準とISO/IEC 10646によって共同で定義されたユニバーサル文字集合に基づいて、ワールドワイドウェブ上の相互運用可能なテキスト操作のための共通の参照を提供します。取り上げられるトピックには、「文字」「エンコーディング」「文字列」の用語の使用、参照処理モデル、文字エンコーディングの選択と識別、文字エスケープ、および文字列のインデックス作成が含まれます。
Unicodeには非常に多くの文字が含まれており、世界の様々な書記体系を取り入れているため、不適切な使用はプログラムやシステムをセキュリティ攻撃にさらす可能性があります。特に、より多くの製品が国際化されるにつれて、これは重要になっています。この文書では、プログラマー、システムアナリスト、標準開発者、およびユーザーが考慮すべきいくつかのセキュリティ上の考慮事項を説明し、問題のリスクを軽減するための具体的な推奨事項を提供しています。
Web Content Accessibility Guidelines (WCAG)は、ウェブコンテンツをよりアクセスしやすくするための広範な推奨事項を網羅しています。これらのガイドラインに従うことで、視覚障害、聴覚障害、学習障害、認知障害、運動制限、言語障害、光過敏症、およびそれらの組み合わせを含む障害を持つ人々に対して、より多くの人々がコンテンツにアクセスできるようになります。また、これらのガイドラインに従うことで、一般的なユーザーにとってもウェブコンテンツがより使いやすくなることがよくあります。
この仕様書は、障害を持つ人々にとってよりアクセスしやすいウェブコンテンツ作成ツールを設計するためのガイドラインを提供します。これらのガイドラインに準拠した作成ツールは、障害を持つ著者にとってアクセス可能なユーザーインターフェースを提供するだけでなく、すべての著者がアクセス可能なウェブコンテンツを作成、サポート、および促進することを可能にします。
この文書は、障害を持つ人々にとってウェブアクセシビリティの障壁を低くするユーザーエージェントを設計するためのガイドラインを提供します。ユーザーエージェントには、ウェブコンテンツを取得してレンダリングするブラウザやその他の種類のソフトウェアが含まれます。これらのガイドラインに準拠したユーザーエージェントは、自身のユーザーインターフェースと他の技術(特に支援技術)と通信する能力を通じてアクセシビリティを促進します。さらに、障害を持つユーザーだけでなく、すべてのユーザーにとって準拠したユーザーエージェントがより使いやすくなるはずです。
この仕様書はInfraに依存しています。 [INFRA]
この仕様書では、HTMLおよびXML属性とIDL属性の両方を参照し、しばしば同じ文脈でそれらを扱います。どちらが参照されているのかが明確でない場合、それらはHTMLおよびXML属性に対してはコンテンツ属性、IDLインターフェースで定義されているものにはIDL属性と呼ばれます。同様に、"プロパティ"という用語は、JavaScriptオブジェクトのプロパティとCSSプロパティの両方に使用されます。これらが曖昧な場合、それぞれオブジェクトプロパティおよびCSSプロパティとして区別されます。
一般的に、仕様書が機能がHTML構文またはXML構文に適用されると述べる場合、それは他方の言語も含まれます。ある機能が特にどちらか一方にのみ適用される場合は、「HTMLの場合、...(これはXMLには適用されません)」のように明確に述べられます。
この仕様書では、ドキュメントという用語は、短い静的ドキュメントからリッチなマルチメディアを含む長いエッセイやレポート、完全なインタラクティブアプリケーションまで、HTMLのあらゆる使用に言及するために使用されます。この用語は、Documentオブジェクトとその子孫DOMツリー、ならびに文脈に応じてHTML構文またはXML構文を使用するシリアル化されたバイトストリームの両方を指すために使用されます。
DOM構造の文脈では、用語HTMLドキュメントおよびXMLドキュメントは、DOMで定義されているように使用され、Documentオブジェクトが置かれる2つの異なるモードを具体的に指します。[DOM](そのような使用は常に定義へのリンクが付けられています。)
バイトストリームの文脈では、HTMLドキュメントという用語はtext/htmlとしてラベル付けされたリソースを指し、XMLドキュメントという用語はXML MIMEタイプとしてラベル付けされたリソースを指します。
簡潔さのために、表示、描画、視覚化のような用語が、ドキュメントがユーザーにどのようにレンダリングされるかを指して使用されることがあります。これらの用語は視覚的な媒体を意味するものではなく、他の媒体にも同等の方法で適用されると見なさなければなりません。
ステップを並行して実行するとは、そのステップが他の標準のロジック(例:イベントループなど)と同時に、一つずつ順番に実行されることを意味します。この標準では、この並行処理がどのように実現されるかについて具体的なメカニズムは定義されていません。例えば、タイムシェアリング協調型マルチタスク、ファイバー、スレッド、プロセス、異なるハイパースレッド、コア、CPU、マシンなどが考えられます。それに対して、即時に実行されるべき操作は、現在実行中のタスクを中断し、自分自身を実行し、その後に先に実行されていたタスクを再開しなければなりません。
並行処理を活用した仕様を記述するためのガイダンスについては、他の仕様からイベントループを扱うを参照してください。
同じデータに対して動作する異なる並行処理アルゴリズム間の競合状態を回避するために、並行キューを使用することができます。
並行キューとは、連続して実行されなければならないアルゴリズムステップのキューを表します。
並行キューには、アルゴリズムキュー(キュー)があり、初期状態では空です。
並行キューにステップをエンキューするには、そのアルゴリズムステップを並行キューのアルゴリズムキューにエンキューします。
新しい並行キューを開始するには、次のステップを実行します。
並行して実行されるステップは、さらに他のステップを並行して実行することができます。例:並行キューの中で、一連のステップをキューと並行して実行することが有用です。
標準がnameList(リスト)を定義し、nameListにnameを追加するメソッドが定義されていると仮定します。ただし、nameListが既にnameを含んでいる場合、それは拒否されます。
次の解決策はレースコンディションの問題を抱えています。
次のステップを並行して実行します。
もしnameListがnameを含んでいる場合、グローバルタスクをキューに追加し、DOM操作タスクソースに与え、thisの関連するグローバルオブジェクトに対して、pをTypeErrorで拒否させ、これらのステップを中止します。
いくつかの潜在的に長時間かかる作業を行います。
追加をnameListに行います。
グローバルタスクをキューに追加し、DOM操作タスクソースに与え、thisの関連するグローバルオブジェクトに対して、pを未定義で解決させます。
pを返します。
上記の2つの呼び出しは同時に実行される可能性があり、ステップ2.1の時点でnameがnameListに存在しないが、ステップ2.3が実行される前にnameが追加される可能性があるため、nameがnameListに2回含まれる結果となります。
並行キューはこの問題を解決します。標準は、nameListQueueを新しい並行キューを開始する結果とし、次のようにします。
次のステップをエンキューし、nameListQueueに追加します。
もしnameListがnameを含んでいる場合、グローバルタスクをキューに追加し、DOM操作タスクソースに与え、thisの関連するグローバルオブジェクトに対して、pをTypeErrorで拒否させ、これらのステップを中止します。
いくつかの潜在的に長時間かかる作業を行います。
追加をnameListに行います。
グローバルタスクをキューに追加し、DOM操作タスクソースに与え、thisの関連するグローバルオブジェクトに対して、pを未定義で解決させます。
pを返します。
このステップはキューに追加され、レース条件が回避されます。
この仕様書では、外部リソースの意味を解釈できる実装がユーザーエージェントにあるかどうかを指す際に、サポートという用語を使用します。あるフォーマットやタイプがサポートされているとは、そのフォーマットやタイプの外部リソースを、リソースの重要な部分が無視されることなく処理できる実装があることを意味します。特定のリソースがサポートされているかどうかは、リソースのフォーマットで使用されている機能によって異なる場合があります。
例えば、PNG画像がサポートされているフォーマットと見なされるのは、そのピクセルデータがデコードされ、レンダリングできる場合です。たとえその画像にアニメーションデータが含まれていたとしても、実装がそれを知らずに処理できるならば、サポートされていると見なされます。
MPEG-4ビデオファイルがサポートされているフォーマットと見なされないのは、使用されている圧縮フォーマットがサポートされていない場合です。たとえ実装がファイルのメタデータからムービーの寸法を判断できたとしても、サポートされているとは見なされません。
一部の仕様書、特にHTTP仕様書で表現と呼ばれるものは、この仕様書ではリソースと呼ばれます。 [HTTP]
リソースの重要なサブリソースとは、リソースが正しく処理されるために利用可能である必要があるサブリソースを指します。どのリソースが重要と見なされるかは、そのリソースのフォーマットを定義する仕様書によって定義されます。
CSSスタイルシートの場合、ここでは暫定的に、@importルールを介してインポートされた他のスタイルシート、及び他のインポートされたスタイルシートによって間接的にインポートされたスタイルシートが重要なサブリソースであると定義します。
この定義は完全に相互運用可能ではありません。さらに、一部のユーザーエージェントは、背景画像やウェブフォントなどのリソースを重要なサブリソースとして扱っているようです。理想的には、CSS作業部会がこれを定義するべきです。進捗を追跡するために、w3c/csswg-drafts issue #1088を参照してください。
HTMLからXMLへの移行を容易にするために、この仕様に準拠するユーザーエージェントは、HTML内の要素を、少なくともDOMとCSSの目的において、http://www.w3.org/1999/xhtml名前空間に配置します。HTML要素という用語は、XML文書内でも、その名前空間にある任意の要素を指します。
特に明記されていない限り、この仕様で定義または言及されているすべての要素は、HTML名前空間("http://www.w3.org/1999/xhtml")にあり、この仕様で定義または言及されているすべての属性には名前空間がありません。
要素型という用語は、特定のローカル名と名前空間を持つ要素の集合を指すために使用されます。例えば、button要素は、button要素型を持つ要素であり、これはそれらが「button」というローカル名と、(上記で定義されたように)HTML名前空間を持つことを意味します。
属性名は、Name生成規則に一致し、U+003A
コロン文字 (:) を含まない場合、XML互換であると言われます。[XML]
ある要素や属性が無視される、別の値として扱われる、または何か他のものとして処理されると記載されている場合、これはノードがDOM内に存在する後の処理のみを指します。このような状況でユーザーエージェントがDOMを変更してはなりません。
コンテンツ属性は、その新しい値が以前の値と異なる場合にのみ変更されるとみなされます。すでに持っている値に属性を設定しても、それは変更とはみなされません。
空という用語が属性値、テキストノード、または文字列に対して使用される場合、それはテキストの長さがゼロであることを意味します(すなわち、制御文字やU+0020スペースさえも含まれていない)。
HTML要素には、その要素のローカル名に対応する特定のHTML要素挿入ステップが定義されている場合があります。同様に、HTML要素には、その要素のローカル名に対応する特定のHTML要素削除ステップが定義されている場合があります。
HTML標準のための挿入ステップは、insertedNodeを引数として以下のように定義されます。
insertedNodeが、その名前空間がHTML名前空間に属する要素であり、この標準がそのinsertedNodeのローカル名に対してHTML要素挿入ステップを定義している場合、その対応するHTML要素挿入ステップをinsertedNodeに対して実行します。
insertedNodeがフォーム関連要素であるか、またはフォーム関連要素の祖先である場合、次のステップを実行します。
そのフォーム関連要素のフォームオーナーをリセットします。
もしinsertedNodeがElement
で、開いている要素のスタックに
ない場合、HTMLパーサーの
内部リソースリンクの処理を行います。
insertedNodeのノードドキュメントに基づいています。
HTML標準のための削除ステップは、removedNodeとoldParentを引数として以下のように定義されます。
documentをremovedNodeのノードドキュメントとして設定します。
もしdocumentのフォーカスされたエリアがremovedNodeである場合、documentのビューポートにdocumentのフォーカスされたエリアを設定し、documentのナビゲーションAPIの進行中のナビゲーション中にフォーカスが変更されたをfalseに設定します。
これによって、フォーカス解除ステップ、フォーカスステップ、またはフォーカス更新ステップは実行されず、そのためblurイベントやchangeイベントは発生しません。
removedNodeが、その名前空間がHTML名前空間に属する要素であり、この標準がそのremovedNodeのローカル名に対してHTML要素削除ステップを定義している場合、その対応するHTML要素削除ステップをremovedNodeとoldParentに対して実行します。
もしremovedNodeのポップオーバー属性がポップオーバーなしの状態にない場合、removedNodeに対してポップオーバーアルゴリズムを非表示にするを実行し、false、false、およびfalseを設定します。
ノードがドキュメントに挿入された場合、それは挿入ステップがそれを引数として実行され、それが今やドキュメントツリー内に存在している場合を指します。同様に、ノードがドキュメントから削除された場合、それは削除ステップがそれを引数として実行され、それが今やドキュメントツリー内にない場合を指します。
ノードが接続されたとき、それは挿入ステップがそれを引数として実行され、それが今や接続された場合を指します。同様に、ノードが接続が解除されたとき、それは削除ステップがそれを引数として実行され、それが今や接続されていない場合を指します。
ノードはブラウジングコンテキストに接続されている場合、それは接続された状態であり、そのシャドウを含むルートのブラウジングコンテキストがnullでない場合を指します。ノードがブラウジングコンテキストに接続されたとき、それは挿入ステップがそれを引数として実行され、それが今やブラウジングコンテキストに接続されている場合を指します。ノードがブラウジングコンテキストから切断された場合、それは削除ステップがそれを引数として実行され、それが今やブラウジングコンテキストに接続されていない場合、またはそのシャドウを含むルートのブラウジングコンテキストがnullになった場合を指します。
Fooという構築は、Fooが実際にはインターフェースである場合、より正確な「インターフェースFooを実装するオブジェクト」という表現の代わりに使われることがあります。
IDL属性は、その値が取得されるとき(例:著者スクリプトによって)に取得中であると言い、新しい値が割り当てられるときに設定中であると言います。
DOMオブジェクトがライブであると言われる場合、そのオブジェクト上の属性やメソッドは、データのスナップショットではなく、実際の基礎データに対して動作しなければなりません。
用語プラグインは、ユーザーエージェントによって使用される
実装依存のコンテンツハンドラーのセットを指し、
Documentオブジェクトのユーザーエージェントのレンダリングに
関与することができますが、子ナビゲーラブルとしては
動作せず、Documentに新しいNodeオブジェクトを
DOMに追加することはありません。
通常、このようなコンテンツハンドラーはサードパーティによって提供されますが、ユーザーエージェントが 組み込みのコンテンツハンドラーをプラグインとして指定することもできます。
ユーザーエージェントは、text/plain
および
application/octet-stream
が登録されたプラグインを持っているとは考えてはなりません。
プラグインの一例としては、ユーザーがPDFファイルに移動するときに、ナビゲーラブルで インスタンス化されるPDFビューアが挙げられます。これは、PDFビューアコンポーネントを実装した 当事者がユーザーエージェント自体を実装した当事者と同じであったかどうかに関係なく、プラグインとして 数えられます。ただし、ユーザーエージェントとは別に起動されるPDFビューアアプリケーション(同じ インターフェースを使用しないもの)は、この定義ではプラグインとは見なされません。
この仕様はプラグインとの相互作用のメカニズムを定義していません。これは、ユーザーエージェントおよびプラットフォーム固有の ものとされているためです。いくつかのユーザーエージェントは、Netscape Plugin APIのようなプラグインメカニズムを サポートすることを選択するかもしれませんし、リモートコンテンツコンバータを使用するか、特定のタイプに対して 組み込みのサポートを持つかもしれません。実際、この仕様はユーザーエージェントにプラグインをサポートするよう 要求していません。[NPAPI]
ブラウザは、プラグイン向けの外部コンテンツと相互作用する際に、 極めて注意するべきです。サードパーティのソフトウェアがユーザーエージェント自体と同じ権限で実行される 場合、そのサードパーティソフトウェアの脆弱性は、ユーザーエージェントの脆弱性と同じくらい危険です。
異なるユーザーが異なるセットのプラグインを持つことは、
ユーザーがユニークに識別される可能性を高めるトラッキングベクターを提供します。そのため、ユーザーエージェントは
各ユーザーに対して正確に同じセットのプラグインをサポートするよう
勧められています。
文字エンコーディング、または それが曖昧でない場合は単にエンコーディングは、バイトストリームとUnicode文字列間の変換方法を定義するものであり、 Encodingで定義されています。エンコーディングにはエンコーディング名と1つ以上のエンコーディングラベルがあり、Encoding標準では エンコーディングの名前とラベルと呼ばれています。[ENCODING]
この仕様書は、ユーザーエージェント(実装者向け)および文書(著者やオーサリングツールの実装者向け)の適合基準について説明しています。
適合文書とは、文書の適合基準をすべて満たす文書のことです。読みやすさのために、これらの適合要件の一部は著者に対する適合要件として表現されていますが、そのような要件は暗黙的に文書に対する要件となります。定義により、すべての文書は著者が存在すると仮定されています(場合によっては、その著者自体がユーザーエージェントであることもあります—その場合、そのユーザーエージェントには追加の規則が適用されます)。
例えば、「著者はfoobar要素を使用してはならない」という要件があれば、それは文書にfoobarという名前の要素を含めてはならないことを意味します。
文書の適合要件と実装の適合要件の間に暗黙の関係はありません。ユーザーエージェントは、非適合文書を自由に扱うことはできません。この仕様書で説明されている処理モデルは、入力文書の適合性に関わらず、実装に適用されます。
ユーザーエージェントは、異なる適合要件を持ついくつかの(重複する)カテゴリに分かれます。
XML構文をサポートするウェブブラウザは、この仕様書で説明されているように、XML文書内にあるHTML名前空間の要素や属性を処理し、ユーザーがそれらと対話できるようにしなければなりません。ただし、他の仕様書によってこれらの要素のセマンティクスが上書きされている場合を除きます。
適合するウェブブラウザは、XML文書内にscript要素を見つけた場合、その要素に含まれるスクリプトを実行します。ただし、その要素がXSLTで表現された変換の中にある場合(ユーザーエージェントがXSLTをサポートしていると仮定して)、プロセッサは代わりにscript要素を変換の一部を構成する不透明な要素として扱います。
HTML構文をサポートするウェブブラウザは、HTML MIMEタイプでラベル付けされた文書を、この仕様書で説明されているように処理し、ユーザーがそれらと対話できるようにしなければなりません。
スクリプトをサポートするユーザーエージェントは、この仕様書に記載されているIDLフラグメントの適合実装でもなければなりません。Web IDL参照。[WEBIDL]
HTML要素のセマンティクスを上書きする仕様書は、通常、その要素を表すDOMオブジェクトに対する要件を上書きしません。例えば、上記の例では、script要素は依然としてHTMLScriptElementインターフェースを実装することになります。
HTMLおよびXML文書を処理して非インタラクティブなバージョンをレンダリングするだけのユーザーエージェントは、ユーザーインタラクションに関する要件を除いて、ウェブブラウザと同じ適合基準を満たさなければなりません。
非インタラクティブなプレゼンテーションユーザーエージェントの典型的な例としては、プリンタ(静的UA)やオーバーヘッドディスプレイ(動的UA)があります。ほとんどの静的非インタラクティブプレゼンテーションユーザーエージェントは、スクリプトのサポートがないことを選択することが期待されます。
非インタラクティブだが動的なプレゼンテーションUAは、スクリプトを実行し、フォームを動的に送信するなどの処理を行います。しかし、ユーザーが文書と対話できない場合、フォーカスの概念は無意味なので、UAはフォーカス関連のDOM APIをサポートする必要はありません。
インタラクティブかどうかにかかわらず、ユーザーエージェントは、この仕様書で定義されている推奨されるデフォルトレンダリングをサポートするものと指定される場合があります(おそらくユーザーオプションとして)。
これは必須ではありません。特に、推奨されるデフォルトレンダリングを実装するユーザーエージェントであっても、ユーザーの体験を向上させるために、このデフォルトをオーバーライドする設定を提供することが推奨されます。例えば、色のコントラストを変更したり、異なるフォーカススタイルを使用したり、ユーザーにとってよりアクセシブルで使いやすい体験を提供するなどです。
推奨されるデフォルトレンダリングをサポートするものとして指定されたユーザーエージェントは、そのように指定されている間、ユーザーエージェントが実装することが期待されると定義されているルールを実装しなければなりません。
スクリプトをサポートしていない、またはスクリプト機能を完全に無効にしている実装は、この仕様書に記載されているイベントおよびDOMインターフェースをサポートする義務はありません。イベントモデルやDOMに基づいて定義されている部分については、そのようなユーザーエージェントは、イベントやDOMがサポートされているかのように動作しなければなりません。
スクリプトはアプリケーションの不可欠な部分を構成することがあります。スクリプトをサポートしていない、またはスクリプトを無効にしているウェブブラウザは、著者の意図を完全に伝えることができないかもしれません。
適合チェッカーは、この仕様書で説明されている適用される適合基準に従って、文書が適合していることを確認しなければなりません。自動適合チェッカーは、著者の意図を解釈する必要があるエラー(例えば、blockquote要素の内容が引用でない場合、文書は適合しないが、人間の判断なしでは適合チェッカーはそれを確認する必要はない)を検出することから免除されます。
適合チェッカーは、ブラウジングコンテキストなしで解析された場合(つまり、スクリプトが実行されず、パーサーのスクリプトフラグが無効になっている)の入力文書が適合していることを確認しなければならず、ブラウジングコンテキストで解析された場合にも文書が適合していることを確認するべきです。そして、スクリプトが一時的にスクリプトの実行中にのみ発生する非適合状態を引き起こさないことを確認するべきです。(これは「SHOULD」であり、「MUST」ではありません。なぜなら、これは不可能であることが証明されているためです。[COMPUTABLE])
"HTMLバリデーター"という用語は、この仕様書の適用される要件に適合する適合チェッカーを指すために使用することができます。
XML DTDは、この仕様書のすべての適合要件を表現することはできません。したがって、バリデーティングXMLプロセッサーとDTDは適合チェッカーを構成することはできません。また、この仕様書で定義されている2つのオーサリングフォーマットのいずれもSGMLのアプリケーションではないため、バリデーティングSGMLシステムも適合チェッカーを構成することはできません。
言い換えれば、適合基準には3つのタイプがあります:
適合チェッカーは、最初の2つをチェックしなければなりません。単純なDTDベースのバリデーターは、最初のクラスのエラーのみをチェックするため、この仕様書に従った適合チェッカーとは見なされません。
HTMLおよびXML文書をレンダリングや適合チェック以外の目的で処理するアプリケーションやツールは、処理する文書のセマンティクスに従って行動するべきです。
例えば、文書のアウトラインを生成するツールが、各段落のネストレベルを増やし、見出しにはネストレベルを増やさない場合、そのツールは適合していないことになります。
オーサリングツールとマークアップ生成ツールは、適合文書を生成しなければなりません。著者に適用される適合基準は、適切な場合、オーサリングツールにも適用されます。
オーサリングツールは、要素を指定された目的のみに使用するという厳しい要件からは免除されますが、これはあくまでオーサリングツールが著者の意図を判断できない場合に限ります。しかし、オーサリングツールは、要素を自動的に誤用したり、ユーザーに誤用を奨励したりしてはなりません。
例えば、任意の連絡先情報にaddress要素を使用することは適合していません。この要素は、最も近いarticle要素やbody要素の先祖に対する連絡先情報のマークアップにのみ使用できます。しかし、オーサリングツールがこの違いを判断することはおそらくできないため、オーサリングツールはその要件から免除されます。ただし、これは、オーサリングツールが任意のイタリック体のテキストブロックにaddress要素を使用できることを意味するわけではなく、ユーザーが連絡先情報の挿入ツールを使用している場合に、そのユーザーが実際に連絡先情報を挿入しているかどうかを確認する必要がないだけです。
適合チェックに関して言えば、エディターは、適合チェッカーが検証する範囲で文書が適合していることを確認しなければなりません。
オーサリングツールが非適合文書を編集する場合、編集セッション中に編集されなかった文書のセクションにおいては、適合エラーを保持することができます(つまり、編集ツールは誤った内容をラウンドトリップさせることが許可されています)。ただし、エラーが保持された場合、オーサリングツールは出力が適合していると主張してはなりません。
オーサリングツールは、大まかに言って、構造やセマンティックデータから作業するツールと、見たままのメディア固有の編集に基づいて作業するツール(WYSIWYG)の2種類に分かれることが期待されます。
前者は、HTMLをオーサリングするツールにとって好ましいメカニズムです。なぜなら、ソース情報の構造を使用して、どのHTML要素や属性が最も適切であるかを判断できるからです。
ただし、WYSIWYGツールも正当なものです。WYSIWYGツールは、自分が適切であると知っている要素を使用し、適切であると知らない要素を使用してはなりません。これにより、極端な場合には、div、b、i、spanなど、わずかな要素に限り、フローレイアウト要素の使用が制限され、style属性が多用される可能性があります。
すべてのオーサリングツール、WYSIWYGかどうかにかかわらず、ユーザーがよく構造化され、セマンティックに豊かで、メディアに依存しないコンテンツを作成できるように最善を尽くすべきです。
既存のコンテンツや以前の仕様書との互換性のため、この仕様書では2つのオーサリングフォーマットについて説明しています:1つはXMLに基づいており、もう1つはSGMLに触発されたカスタムフォーマット(HTML構文と呼ばれます)です。実装はこれら2つの形式の少なくとも1つをサポートしなければなりませんが、両方をサポートすることが奨励されています。
いくつかの適合要件は、要素、属性、メソッド、またはオブジェクトに対する要件として表現されています。このような要件は、コンテンツモデルの制約を説明するものと、実装の動作を説明するものに分類されます。前者は文書やオーサリングツールに対する要件であり、後者はユーザーエージェントに対する要件です。同様に、いくつかの適合要件は、著者に対する要件として表現されています。そのような要件は、著者が生成する文書に対する適合要件として解釈されるべきです(つまり、この仕様書は、著者に対する適合基準と文書に対する適合基準を区別していません)。
この仕様は、いくつかの他の基本的な仕様に依存しています。
以下の用語はInfraで定義されています: [INFRA]
Unicode文字セットはテキストデータを表すために使用され、エンコーディング は文字エンコーディングに関する要件を定義します。 [UNICODE]
この仕様は用語を導入しています それらの仕様で定義された用語に基づいていますが、前述のように説明されています。
以下の用語はエンコーディングで定義されているように使用されます:[ENCODING]
HTMLのXML構文をサポートする実装は、いくつかのバージョンのXMLとその対応する名前空間仕様をサポートする必要があります。なぜなら、その構文は名前空間を持つXMLシリアル化を使用しているからです。[XML] [XMLNS]
データマイニングツールやスクリプトを実行せずにコンテンツを操作する他のユーザーエージェント、CSSやXPath式を評価する、またはそれ以外の方法で結果のDOMを任意のコンテンツに公開する場合、「名前空間をサポート」するには、単にそのDOMノードアナログが特定の名前空間に属していると主張するだけでよく、実際に名前空間文字列を公開する必要はありません。
HTML構文では、名前空間接頭辞や名前空間宣言はXMLでの同様の効果を持たないことに注意してください。たとえば、HTML要素名ではコロンに特別な意味はありません。
名前spaceを持つ属性は、XML名前空間で定義されています。
拡張可能なマークアップ言語(XML)で定義されています。[XML]
Name
の生成規則はXMLで定義されています。
[XML]
この仕様はまた、<?xml-stylesheet?>
処理命令に言及しています。これはXML文書にスタイルシートを関連付けるで定義されています。
[XMLSSPI]
この仕様では、XSLTProcessor
インターフェースとそのtransformToFragment()およびtransformToDocument()メソッドにも非公式に言及しています。
[XSLTP]
以下の用語はURLで定義されています: [URL]
application/x-www-form-urlencoded形式
application/x-www-form-urlencodedシリアライザ
この仕様では、次のスキームやプロトコルも参照しています:
about:
スキーム
[ABOUT]
blob:
スキーム
[FILEAPI]
data:
スキーム
[RFC2397]
http:スキーム
[HTTP]
https:スキーム
[HTTP]
mailto:
スキーム [MAILTO]
sms:スキーム
[SMS]
urn:スキーム
[URN]
メディアフラグメント構文はメディアフラグメントURIで定義されています。[MEDIAFRAG]
以下の用語はHTTP仕様で定義されています: [HTTP]
Accept`
ヘッダー
Accept-Language`
ヘッダー
Cache-Control`
ヘッダー
Content-Disposition`
ヘッダー
Content-Language`
ヘッダー
Content-Range`
ヘッダー
Last-Modified`
ヘッダー
Range`
ヘッダー
Referer`
ヘッダー
次の用語はHTTPステートマネジメントメカニズムで定義されています: [COOKIES]
次の用語はWebリンクで定義されています: [WEBLINK]
Link`ヘッダー
次の用語はHTTPの構造化フィールド値で定義されています: [STRUCTURED-FIELDS]
次の用語はMIMEスニッフィングで定義されています: [MIMESNIFF]
次の用語はFetchで定義されています: [FETCH]
about:blank
User-Agent`値
Origin`ヘッダー
Cross-Origin-Resource-Policy`
ヘッダー
RequestCredentials
列挙
RequestDestination
列挙
fetch()
メソッド
次の用語はリファラーポリシーで定義されています: [REFERRERPOLICY]
Referrer-Policy`
HTTPヘッダー
Referrer-Policy`ヘッダーから
リファラーポリシーを解析するアルゴリズム
no-referrer」、
「no-referrer-when-downgrade」、
「origin-when-cross-origin」、
および
「unsafe-url」
リファラポリシー
次の用語はMixed Contentで定義されています: [MIX]
次の用語はSubresource Integrityで定義されています: [SRI]
以下の用語はペイントタイミングで定義されています:[PAINTTIMING]
以下の用語はナビゲーションタイミングで定義されています:[NAVIGATIONTIMING]
NavigationTimingTypeとその
"navigate",
"reload",
および
"back_forward"
の値。
以下の用語はリソースタイミングで定義されています:[RESOURCETIMING]
以下の用語はパフォーマンスタイムラインで定義されています:[PERFORMANCETIMELINE]
PerformanceEntryとその
name,
entryType,
startTime,
および
duration
属性。
以下の用語はロングアニメーションフレームで定義されています:[LONGANIMATIONFRAMES]
以下の用語はロングタスクで定義されています:[LONGTASKS]
この仕様書に記載されているIDLフラグメントは、Web IDLで記述された準拠IDLフラグメントとして解釈されなければなりません。[WEBIDL]
以下の用語はWeb IDLで定義されています:
[Global]
[LegacyFactoryFunction]
[LegacyLenientThis]
[LegacyNullToEmptyString]
[LegacyOverrideBuiltIns]
LegacyPlatformObjectGetOwnProperty
[LegacyTreatNonObjectAsNull]
[LegacyUnenumerableNamedProperties]
[LegacyUnforgeable]
Web IDLはまた、この仕様書のWeb IDLフラグメントで使用されている以下のタイプを定義しています:
ArrayBuffer
ArrayBufferView
boolean
DOMString
double
Function
long
object
Promise
Uint8ClampedArray
unrestricted double
unsigned long
USVString
VoidFunction
この仕様書でスローという用語はWeb
IDLで定義されている意味で使用されます。DOMExceptionタイプと、次の例外名はWeb
IDLで定義され、この仕様書で使用されています:
IndexSizeError"
HierarchyRequestError"
InvalidCharacterError"
NoModificationAllowedError"
NotFoundError"
NotSupportedError"
InvalidStateError"
SyntaxError"
InvalidAccessError"
SecurityError"
NetworkError"
AbortError"
QuotaExceededError"
DataCloneError"
EncodingError"
NotAllowedError"
この仕様書がユーザーエージェントに、特定の時間を表すDateオブジェクトを作成する(それは特別な値Not-a-Numberである可能性がある)ことを要求する場合、その時間のミリ秒コンポーネントがあれば、それは整数に切り捨てられ、生成された新しいDateオブジェクトの時間値は、切り捨てられた時間を表さなければなりません。
例えば、2000年1月1日00:00:00.023045Zの23045ミリオンズ秒後の時間を考えた場合、作成されたDateオブジェクトは、同じ時間を表すもので、その時間は2000年1月1日00:00:00.023Z、すなわち45ミリオンズ秒前の時間と同じです。指定された時間がNaNである場合、結果は特定の瞬間を表さないDateオブジェクトになります。
この仕様書で記述されている言語の一部は、基盤となるスクリプト言語としてJavaScriptのみをサポートします。[JAVASCRIPT]
「JavaScript」という用語は、ECMA-262ではなく、JavaScriptという用語が広く知られているため、使用されています。
以下の用語はJavaScript仕様書で定義され、この仕様書で使用されています:
Atomicsオブジェクト
Atomics.waitAsyncオブジェクト
Dateクラス
FinalizationRegistryクラス
RegExpクラス
SharedArrayBufferクラス
SyntaxErrorクラス
TypeErrorクラス
RangeErrorクラス
WeakRefクラス
eval()関数
WeakRef.prototype.deref()関数
import()
import.meta
typeof演算子
delete演算子
JavaScript をサポートするユーザーエージェントは、Dynamic Code Brand Checks 提案も実装しなければなりません。以下の用語はこの提案で定義され、本仕様で使用されています: [JSDYNAMICCODEBRANDCHECKS]
JavaScript をサポートするユーザーエージェントは、ECMAScript Internationalization API も実装しなければなりません。[JSINTL]
JavaScript をサポートするユーザーエージェントは、Import Attributes 提案も実装しなければなりません。以下の用語はこの提案で定義され、本仕様で使用されています: [JSIMPORTATTRIBUTES]
JavaScript をサポートするユーザーエージェントは、JSON modules 提案も実装しなければなりません。以下の用語はこの提案で定義され、本仕様で使用されています: [JSJSONMODULES]
JavaScript をサポートするユーザーエージェントは、Resizable ArrayBuffer and growable SharedArrayBuffer 提案も実装しなければなりません。以下の用語はこの提案で定義され、本仕様で使用されています: [JSRESIZABLEBUFFERS]
JavaScript をサポートするユーザーエージェントは、Temporal 提案も実装しなければなりません。以下の用語はこの提案で定義され、本仕様で使用されています: [JSTEMPORAL]
以下の用語は WebAssembly JavaScript Interface で定義されています: [WASMJS]
文書オブジェクトモデル(DOM)は、文書とその内容の表現、つまりモデルです。DOM は API だけではなく、HTML 実装の準拠基準がこの仕様で定義されており、DOM 上の操作に基づいています。[DOM]
実装は DOM と UI Events で定義されたイベントをサポートする必要があります。なぜなら、この仕様は DOM に基づいて定義されており、一部の機能は DOM インターフェースの拡張として定義されているからです。[DOM] [UIEVENTS]
特に、以下の機能が DOM に定義されています:[DOM]
Attr
インターフェース
CharacterData
インターフェース
Comment
インターフェース
DOMImplementation
インターフェース
Document
インターフェースとその
doctype 属性
DocumentOrShadowRoot
インターフェース
DocumentFragment
インターフェース
DocumentType
インターフェース
ChildNode
インターフェース
Element
インターフェース
attachShadow()
メソッド
Node
インターフェース
NodeList
インターフェース
ProcessingInstruction
インターフェース
ShadowRoot
インターフェース
Text
インターフェース
Range
インターフェース
HTMLCollection
インターフェース、およびその
length
属性、およびその
item()
および
namedItem()
メソッド
DOMTokenList
インターフェース、その
value
属性と
supports
操作
createDocument()
メソッド
createHTMLDocument()
メソッド
createElement()
メソッド
createElementNS()
メソッド
getElementById()
メソッド
getElementsByClassName()
メソッド
appendChild()
メソッド
cloneNode()
メソッド
importNode()
メソッド
preventDefault()
メソッド
id 属性
setAttribute()
メソッド
textContent
属性
slotchange
イベント
CharacterData
node and its
replace
data アルゴリズム
Event
インターフェース
Event
および派生インターフェースのコンストラクターの動作
EventTarget
インターフェース
EventInit 辞書型
type 属性
currentTarget
属性
bubbles 属性
cancelable
属性
composed 属性
isTrusted
属性
initEvent()
メソッド
addEventListener()
メソッド
EventListener
コールバックインターフェース
Document
Node、
およびそのアルゴリズムで使用される
cloning steps 概念
is
value
MutationObserver
インターフェース、および mutation observers 全般
AbortController
とその
signal
AbortSignal
以下の機能は UI Events で定義されています:[UIEVENTS]
MouseEvent
インターフェース
MouseEvent
インターフェースの relatedTarget
属性
MouseEventInit
辞書型
FocusEvent
インターフェース
FocusEvent
インターフェースの relatedTarget
属性
UIEvent
インターフェース
UIEvent
インターフェースの view 属性
auxclick
イベント
beforeinput
イベント
click イベント
contextmenu
イベント
dblclick
イベント
input イベント
mousedown
イベント
mouseenter
イベント
mouseleave
イベント
mousemove
イベント
mouseout
イベント
mouseover
イベント
mouseup
イベント
wheel イベント
keydown
イベント
keypress
イベント
keyup イベント
以下の機能は Touch Events で定義されています:[TOUCH]
Touch
インターフェース
touchend
イベント
以下の機能は Pointer Events で定義されています:[POINTEREVENTS]
PointerEvent
インターフェース
PointerEvent
インターフェースの pointerType
属性
pointerdown
イベント
pointerup
イベント
pointercancel
イベント
以下のイベントは Clipboard API and events で定義されています:[CLIPBOARD-APIS]
この仕様では、イベントのtypeを指すために name
という用語を使用することがあります。たとえば、「click という名前のイベント」や「イベント名が keypress
の場合」のように、イベントの「name」と「type」は同義です。
以下の機能は DOM Parsing and Serialization で定義されています:[DOMPARSING]
以下の機能は Selection API で定義されています:[SELECTION]
ユーザーエージェントは、execCommand で説明されている機能を実装することが推奨されます。[EXECCOMMAND]
以下の機能は Fullscreen API で定義されています:[FULLSCREEN]
requestFullscreen()
fullscreenchange
High Resolution Time は、以下の機能を提供します:[HRT]
この仕様は、ファイルAPIで定義されている以下の機能を使用しています: [FILEAPI]
Blob
インターフェースとその
type属性
File
インターフェースとその
nameおよび
lastModified
属性
FileList
インターフェース
Blobの
スナップショット状態
の概念
この仕様は、インデックス付きデータベーストランザクションのクリーンアップ として定義されている機能を使用しています。インデックス付きデータベースAPIで定義されています。 [INDEXEDDB]
以下の用語はメディアソース拡張で定義されています: [MEDIASOURCE]
MediaSource
インターフェース
以下の用語はメディアキャプチャとストリームで定義されています: [MEDIASTREAM]
MediaStream
インターフェース
以下の用語はレポーティングで定義されています: [REPORTING]
以下の機能と用語はXMLHttpRequestで定義されています: [XHR]
XMLHttpRequest
インターフェースとその
responseXML
属性
ProgressEvent
インターフェースとその
lengthComputable、
loaded、
total
属性
FormData
インターフェースとその関連する
エントリリスト
以下の機能はバッテリーステータスAPIで定義されています: [BATTERY]
getBattery()
メソッド
実装にはメディアクエリをサポートする必要があります。<media-condition> 機能はそこに定義されています。[MQ]
この仕様の実装にはCSS全体のサポートは必要ありません(ただし、特にウェブブラウザ向けには推奨されます)が、一部の機能は特定のCSS要件に基づいて定義されています。
この仕様が何かを特定のCSS文法に従って解析 する必要があると要求する場合、CSS構文の関連アルゴリズムに従う必要があります。 エラーハンドリングルールを含みます。[CSSSYNTAX]
たとえば、スタイルシートの終わりが予期せず見つかった場合、すべての開いた構造体を閉じるように、ユーザーエージェントは要求されます。このため、
色の値として "rgb(0,0,0"(閉じかっこが不足している)の文字列を解析するとき、このエラーハンドリングルールにより閉じかっこが暗黙的に追加され、色 '黒'
が得られます。ただし、類似の構造体 "rgb(0,0,"(閉じかっこと「青」値が不足している)の場合、開いている構造体を閉じても有効な値が得られないため、解析できません。
以下の用語と機能はカスケーディングスタイルシート (CSS)で定義されています:[CSS]
'display'プロパティの基本バージョンはCSSで定義されており、そのプロパティは他のCSSモジュールによって拡張されています。 [CSS] [CSSRUBY] [CSSTABLE]
以下の用語と機能はCSSボックスモデルで定義されています: [CSSBOX]
以下の機能はCSS Logical Propertiesで定義されています: [CSSLOGICAL]
以下の用語と機能はCSS Colorで定義されています: [CSSCOLOR]
以下の用語はCSS Imagesで定義されています: [CSSIMAGES]
ペイントソース という用語はCSS Images Level 4で定義されており、特定のHTML要素とCSSの'element()'関数の 相互作用を定義するために使用されます。 [CSSIMAGES4]
以下の機能はCSS Backgrounds and Bordersで定義されています: [CSSBG]
CSS Backgrounds and Bordersは、次のボーダープロパティも定義しています: [CSSBG]
以下の機能はCSS Box Alignmentで定義されています: [CSSALIGN]
以下の用語と機能はCSS Displayで定義されています: [CSSDISPLAY]
CSS Flexible Box Layoutで次の機能が定義されています: [CSSFLEXBOX]
CSS Fontsで次の用語と機能が定義されています: [CSSFONTS]
CSS Grid Layoutで次の機能が定義されています: [CSSGRID]
CSS Inline Layoutで次の用語が定義されています: [CSSINLINE]
CSS Box Sizingで次の用語と機能が定義されています: [CSSSIZING]
CSS Lists and Countersで次の機能が定義されています。 [CSSLISTS]
CSS Overflowで次の機能が定義されています。 [CSSOVERFLOW]
CSS Positioned Layoutで次の用語と機能が定義されています: [CSSPOSITION]
CSS Multi-column Layoutで次の機能が定義されています。 [CSSMULTICOL]
'ruby-base' 値はCSS Ruby Layoutで定義されています。 [CSSRUBY]
CSS Tableで次の機能が定義されています: [CSSTABLE]
CSS Textで次の機能が定義されています: [CSSTEXT]
CSS Writing Modesで次の機能が定義されています: [CSSWM]
CSS Basic User Interfaceで次の機能が定義されています: [CSSUI]
アニメーションを更新してイベントを送信するアルゴリズムupdate animations and send eventsはWeb Animationsに定義されています。 [WEBANIMATIONS]
スクリプトをサポートする実装は、CSSオブジェクトモデルをサポートする必要があります。以下の機能と用語はCSSOM仕様で定義されています:[CSSOM] [CSSOMVIEW]
Screen
インターフェース
LinkStyle
インターフェース
CSSStyleDeclaration
インターフェース
style
IDL属性
cssText
属性CSSStyleDeclaration
StyleSheet
インターフェース
CSSStyleSheet
インターフェース
CSSStyleSheetを作成する
CSSStyleSheetのルールを同期的に置き換える
resize
イベント
scroll
イベント
scrollend
イベント
以下の機能と用語はCSS Syntaxで定義されています: [CSSSYNTAX]
以下の用語はSelectorsで定義されています:[SELECTORS]
以下の機能はCSS Values and Unitsで定義されています: [CSSVALUES]
以下の機能はCSS View Transitionsで定義されています: [CSSVIEWTRANSITIONS]
ViewTransition
スタイル属性という用語は、CSS Style Attributesで定義されています。[CSSATTR]
以下の用語はCSS Cascading and Inheritanceで定義されています: [CSSCASCADE]
CanvasRenderingContext2D
オブジェクトのフォント使用は、CSSFontsおよびFont Loading仕様に記載された機能に依存し、特にFontFaceオブジェクトとフォントソースの概念に依存します。
[CSSFONTS] [CSSFONTLOAD]
以下のインターフェースと用語はGeometry Interfacesで定義されています: [GEOMETRY]
DOMMatrix
インターフェース、および関連する
m11
要素,
m12
要素,
m21
要素,
m22
要素,
m41
要素, および
m42
要素
DOMMatrix2DInit
および
DOMMatrixInit
辞書
DOMMatrixを作成する
および2D辞書からDOMMatrixを作成する
アルゴリズムはDOMMatrix2DInit
またはDOMMatrixInitを使用します。
DOMPointInit
辞書、および関連する
x
および
y
メンバー
以下の用語はCSS Scopingで定義されています:[CSSSCOPING]
以下の用語と機能はCSS Color Adjustmentで定義されています: [CSSCOLORADJUST]
以下の用語はCSS Pseudo-Elementsで定義されています:[CSSPSEUDO]
以下の用語はCSS Containmentで定義されています:[CSSCONTAIN]
以下の用語はIntersection Observerで定義されています: [INTERSECTIONOBSERVER]
以下の用語はResize Observerで定義されています: [RESIZEOBSERVER]
以下のインターフェースはWebGL仕様で定義されています:[WEBGL]
WebGLRenderingContext
インターフェース
WebGL2RenderingContext
インターフェース
WebGLContextAttributes
辞書
以下のインターフェースはWebGPUで定義されています:[WEBGPU]
GPUCanvasContext
インターフェース
実装は、字幕、キャプション、メタデータなどのテキストトラックフォーマットとしてWebVTTをサポートする場合があります。[WEBVTT]
この仕様で使用されている以下の用語はWebVTTで定義されています:
VTTCue
インターフェース
role属性は
Accessible Rich Internet Applications (ARIA)で定義されており、以下のロールも同様です:[ARIA]
さらに、以下のaria-*コンテンツ属性はARIAで定義されています:[ARIA]
最後に、以下の用語はARIAで定義されています:[ARIA]
ARIAMixinインターフェース、
その関連する
ARIAMixin
ゲッターステップおよび
ARIAMixin
セッターステップフック
以下の用語はコンテンツセキュリティポリシーで定義されています: [CSP]
report-uriディレクティブ
frame-ancestorsディレクティブ
sandboxディレクティブ
SecurityPolicyViolationEvent
インターフェイス
securitypolicyviolation
イベント
以下の用語はサービスワーカーで定義されています: [SW]
ServiceWorker
インターフェイス
ServiceWorkerContainer
インターフェイス
ServiceWorkerGlobalScope
インターフェイス
以下のアルゴリズムはセキュアコンテキストで定義されています: [SECURE-CONTEXTS]
以下の用語はパーミッションポリシーで定義されています: [PERMISSIONSPOLICY]
以下の機能はペイメントリクエストAPIで定義されています: [PAYMENTREQUEST]
PaymentRequest
インターフェイス
MathML全体のサポートはこの仕様では必須ではありません(ただし、少なくともウェブブラウザには推奨されています)が、特定の機能はMathMLの一部を実装していることに依存しています。 [MATHML]
以下の機能は数式マークアップ言語 (MathML)で定義されています:
SVG全体のサポートはこの仕様では必須ではありません(ただし、少なくともウェブブラウザには推奨されています)が、特定の機能はSVGの一部を実装していることに依存しています。
SVGを実装するユーザーエージェントは、SVG 2仕様を実装し、それ以前のリビジョンを実装してはなりません。
以下の機能はSVG 2仕様で定義されています: [SVG]
SVGElement
インターフェイス
SVGImageElement
インターフェイス
SVGScriptElement
インターフェイス
SVGSVGElement
インターフェイス
a要素
desc要素
foreignObject要素
image要素
script要素
svg要素
title要素
use要素
text-renderingプロパティ
以下の機能はフィルター効果で定義されています: [FILTERS]
以下の機能はコンポジットとブレンディングで定義されています: [COMPOSITE]
以下の機能はバックグラウンドタスクの協調スケジューリングで定義されています: [REQUESTIDLECALLBACK]
以下の用語は画面の向きで定義されています: [SCREENORIENTATION]
以下の用語はストレージで定義されています: [STORAGE]
以下の機能はウェブアプリマニフェストで定義されています: [MANIFEST]
以下の機能はWebCodecsで定義されています: [WEBCODECS]
VideoFrame
インターフェイス。
以下の用語はWebDriverで定義されています: [WEBDRIVER]
以下の用語はWebDriver BiDiで定義されています: [WEBDRIVERBIDI]
以下の用語はWeb Cryptography APIで定義されています: [WEBCRYPTO]
以下の用語はWebSocketsで定義されています: [WEBSOCKETS]
以下の用語はWebTransportで定義されています: [WEBTRANSPORT]
以下の用語は公開鍵証明書にアクセスするためのAPIであるウェブ認証で定義されています: [WEBAUTHN]
以下の用語は資格管理で定義されています: [CREDMAN]
以下の用語はコンソールで定義されています: [CONSOLE]
以下の用語はウェブロックAPIで定義されています: [WEBLOCKS]
この仕様では、Trusted Typesで定義された以下の機能を使用します: [TRUSTED-TYPES]
この仕様は、特定のネットワークプロトコル、スタイルシート言語、スクリプト言語、または上記リストで要求されている以外のDOM仕様のサポートを必須とはしません。しかし、この仕様で記述されている言語は、スタイリング言語としてCSS、スクリプト言語としてJavaScript、ネットワークプロトコルとしてHTTPに偏っており、いくつかの機能はこれらの言語やプロトコルが使用されていることを前提としています。
HTTPプロトコルを実装するユーザーエージェントは、HTTPステートマネジメントメカニズム(クッキー)も実装しなければなりません。[HTTP] [COOKIES]
この仕様は、各セクションにおいて文字エンコーディング、画像フォーマット、オーディオフォーマット、およびビデオフォーマットに関する追加の要件を持つ可能性があります。
ベンダー固有のプロプライエタリなユーザーエージェント拡張は、この仕様に対して強く推奨されません。文書はそのような拡張を使用してはならず、そのような行為は相互運用性を低下させ、ユーザーベースを断片化し、特定のユーザーエージェントのユーザーだけが問題のコンテンツにアクセスできるようにしてしまいます。
すべての拡張は、この仕様で定義された機能に矛盾を生じさせたり、不適合を引き起こしたりしないように定義されなければなりません。
例えば、強く推奨されていないものの、実装がコントロールに新しいIDL属性「typeTime」を追加し、ユーザーが現在の値を選択するのにかかった時間を返す(仮に)ことが考えられます。一方で、フォームのelements配列に新しいコントロールを定義することは、上記の要件に違反します。これは、この仕様で定義されたelementsの定義に違反するからです。
この仕様に対してベンダー中立の拡張が必要な場合は、この仕様を適切に更新するか、またはこの仕様の要件を上書きする拡張仕様を作成することができます。この仕様を適用する人が、その拡張仕様の要件を認識することを決定した場合、その拡張仕様は、この仕様における適合要件の目的で適用可能な仕様となります。
誰かが任意のバイトストリームを適合すると定義する仕様を作成し、その無作為なデータが適合していると主張することは可能です。しかし、それは他の人にとってもその無作為なデータが適合していることを意味するわけではありません。もし誰かがその仕様が自分の作業には適用されないと決定した場合、彼らはその無作為なデータが単なるゴミであり、まったく適合していないと正当に言うことができます。適合に関して重要なのは、その特定のコミュニティが同意するものが適用可能であるということです。
ユーザーエージェントは、理解できない要素や属性を意味的に中立として扱わなければなりません。これらをDOMに残し(DOMプロセッサ向け)、CSSに従ってスタイリングし(CSSプロセッサ向け)、そこから何らかの意味を推測してはなりません。
機能のサポートが無効になった場合(例: セキュリティ問題を緩和するための緊急措置、開発を支援するため、またはパフォーマンスの理由で)、ユーザーエージェントは、その機能が全くサポートされていないかのように行動し、この仕様でその機能が言及されていないかのように扱わなければなりません。例えば、特定の機能がWeb IDLインターフェースの属性を介してアクセスされる場合、その属性自体をそのインターフェースを実装するオブジェクトから除外しなければなりません—オブジェクトに属性を残しておきながら、nullを返すか、例外をスローするのでは不十分です。
HTML文書に関するこの仕様で記述されている方法で解析または作成されたXPath
1.0の実装(例えば、document.evaluate() APIの一部として)は、次の編集がXPath 1.0仕様に適用されたかのように動作しなければなりません。
まず、この段落を削除します:
QNameは、ノードテスト内で式コンテキストの名前空間宣言を使用して
展開名に展開されます。これは、開始タグと終了タグでの要素型名の展開と同じ方法ですが、xmlnsで宣言されたデフォルト名前空間は使用されません。QNameにプレフィックスがない場合、名前空間URIはnullになります(これは属性名が展開される方法と同じです)。QNameにプレフィックスがあり、式コンテキストに名前空間宣言がない場合、それはエラーです。
次に、次の内容をその場所に挿入します:
ノードテスト内のQNameは、式コンテキストの名前空間宣言を使用して展開名に展開されます。QNameにプレフィックスがある場合、そのプレフィックスに対応する名前空間URIが式コンテキストに存在しなければなりません。そのプレフィックスに対応する名前空間URIがそのプレフィックスに関連付けられたものです。QNameにプレフィックスがあり、式コンテキストに名前空間宣言がない場合、それはエラーです。
QNameにプレフィックスがなく、軸の主要ノード型が要素である場合、デフォルト要素名前空間が使用されます。それ以外の場合、QNameにプレフィックスがない場合、名前空間URIはnullです。デフォルト要素名前空間は、XPath式のコンテキストのメンバーです。DOM3 XPath APIを使用してXPath式を実行する際のデフォルト要素名前空間の値は、次の方法で決定されます:
- コンテキストノードがHTML DOMからのものである場合、デフォルト要素名前空間は「http://www.w3.org/1999/xhtml」です。
- それ以外の場合、デフォルト要素名前空間URIはnullです。
これは、XPath 2.0のデフォルト要素名前空間機能をXPath 1.0に追加し、HTML文書に対してHTML名前空間をデフォルト要素名前空間として使用することに相当します。この変更は、レガシーHTMLコンテンツとの互換性を保ちながら、この仕様がHTML要素に使用する名前空間に関して導入する変更をサポートするため、およびXPath 2.0ではなくXPath 1.0を使用することを望むことに動機付けられています。
この変更は、HTML要素に使用される名前空間に関してこの仕様が導入する変更をサポートしながらも、レガシーコンテンツとの互換性を保つことを目的とした、XPath 1.0仕様の故意の違反です。[XPATH10]
出力メソッドが「html」である場合(明示的に指定された場合、またはXSLT 1.0のデフォルト規則により)、DOMに出力するXSLT 1.0プロセッサーは次のように影響を受けます:
変換プログラムが名前空間を持たない要素を出力する場合、プロセッサは対応するDOM要素ノードを構築する前に、その要素の名前空間をHTML名前空間に変更し、要素のローカル名をASCII小文字に変換し、要素上の非名前空間属性の名前もASCII小文字に変換しなければなりません。
この要件は、DOMベースのXSLT変換と互換性がない方法でHTMLの名前空間および大文字小文字の区別のルールを変更するこの仕様が原因で必要とされる、XSLT 1.0仕様の故意の違反です。(出力をシリアル化するプロセッサーは影響を受けません。)[XSLT10]
この仕様は、XSLT処理がHTMLパーサーインフラストラクチャとどのように相互作用するかを正確には指定していません(例えば、XSLTプロセッサーが何らかの要素をオープン要素のスタックに配置するかのように動作するかどうか)。しかし、XSLTプロセッサーは成功した場合には解析を停止し、処理が中止された場合には、まず現在の文書の準備状況を「interactive」に更新し、その後「complete」に更新する必要があります。
この仕様は、XSLTがナビゲーションアルゴリズムとどのように相互作用するか、イベントループとどのように適合するか、またはエラーページがどのように処理されるか(例: XSLTエラーが増分XSLT出力を置き換えるか、インラインでレンダリングされるかなど)を指定していません。
XSLTとHTML、XSLT、XPath、およびHTMLの相互作用に関しては、script要素セクションおよびtemplate要素セクションに非規範的なコメントが追加されています。
Headers/Permissions-Policy/document-domain
1つのエンジンのみでのサポート。
この文書では、以下のポリシーで制御される機能を定義しています:
Headers/Feature-Policy/autoplay
Headers/Permissions-Policy/autoplay
1つのエンジンのみでのサポート。
autoplay"は、デフォルトの許可リストが'self'の機能です。
cross-origin-isolated"は、デフォルトの許可リストが'self'の機能です。
HTMLには、日付や数値など、特定のデータ型を受け入れるさまざまな場所があります。このセクションでは、そのようなフォーマットのコンテンツに対する適合基準と、それらを解析する方法について説明します。
実装者は、以下で説明する構文の解析を実装するために使用する可能性のあるサードパーティのライブラリを慎重に検討することを強く推奨します。たとえば、日付ライブラリは、この仕様で要求されるエラーハンドリング動作とは異なる動作を実装する可能性があります。これは、日付構文に関する仕様ではエラーハンドリング動作が定義されていないことが多く、そのため実装によってエラーの処理方法が大きく異なるからです。
以下で説明するいくつかのマイクロパーサーは、解析される文字列を保持するinput変数と、input内で次に解析される文字にポインタを指すposition変数を持つパターンに従います。
多くの属性がブール属性です。要素にブール属性が存在する場合、その値はtrueを表し、属性が存在しない場合はfalseを表します。
属性が存在する場合、その値は空の文字列であるか、属性の正規名に対してASCII大文字小文字を区別しない一致を持つ値でなければなりません。また、その値には前後に空白があってはなりません。
ブール属性には「true」や「false」の値を指定することはできません。false値を表すには、属性を完全に省略する必要があります。
ここにチェックされ、無効化されたチェックボックスの例があります。checked属性とdisabled属性がブール属性です。
< label >< input type = checkbox checked name = cheese disabled > Cheese</ label >
これは次のように書くこともできます:
< label >< input type = checkbox checked = checked name = cheese disabled = disabled > Cheese</ label >
また、スタイルを混ぜても、次のようにしても同等です:
< label >< input type = 'checkbox' checked name = cheese disabled = "" > Cheese</ label >
列挙型属性と呼ばれる属性は、有限の状態を持ちます。このような属性の状態は、属性の値、各属性の仕様に記載されているキーワード/状態のマッピングセット、および属性の仕様に記載されている2つの特別な状態を組み合わせて導き出されます。これらの特別な状態は、無効値デフォルトと欠損値デフォルトです。
複数のキーワードが同じ状態にマップされることがあります。
空の文字列が有効なキーワードである場合があります。欠損値デフォルトは、属性が欠損している場合にのみ適用され、空の文字列が指定されている場合には適用されないことに注意してください。
属性の状態を決定するには、以下の手順を使用します:
属性が指定されていない場合:
属性の値が、その属性に定義されているキーワードのいずれかとASCII大文字小文字を区別しない一致である場合、そのキーワードで表される状態を返します。
状態を返しません。
著作適合性の目的のために、列挙型属性が指定されている場合、その属性の値は、その属性の適合キーワードのいずれかとASCII大文字小文字を区別しない一致であり、先頭または末尾に空白がないものでなければなりません。
反映の目的のために、キーワードがマップされている状態は正規キーワードを持つと言われます。これは以下のように決定されます:
指定された状態にマップされているキーワードが1つだけの場合、それがそのキーワードです。
指定された状態にマップされている適合するキーワードが1つだけの場合、それがその適合するキーワードです。
それ以外の場合、状態の正規キーワードはその属性の仕様に明示的に記載されます。
文字列が1つ以上のASCII数字で構成されており、任意でU+002D HYPHEN-MINUS文字(-)で始まる場合、その文字列は有効な整数です。
U+002D HYPHEN-MINUS(-)プレフィックスがない有効な整数は、その数字列が表す10進数の値を表します。U+002D HYPHEN-MINUS(-)プレフィックスがある有効な整数は、U+002D HYPHEN-MINUSの後に続く数字列が表す10進数の値をゼロから引いた値を表します。
整数を解析するためのルールは、次のアルゴリズムで示されています。このアルゴリズムが呼び出されたときは、指定された順序でステップを実行し、値を返す最初のステップで中止しなければなりません。このアルゴリズムは、整数またはエラーのいずれかを返します。
inputを解析中の文字列とします。
positionをinput内のポインタとし、最初は文字列の先頭を指します。
signには「正」の値を設定します。
ASCII空白文字をスキップし、positionをinput内の次の位置に進めます。
positionがinputの終端を超えている場合、エラーを返します。
positionが指している文字(最初の文字)がU+002D HYPHEN-MINUS文字(-)の場合:
signを「負」に設定します。
positionを次の文字に進めます。
positionがinputの終端を超えている場合、エラーを返します。
それ以外の場合、positionが指している文字(最初の文字)がU+002B PLUS SIGN文字(+)の場合:
positionを次の文字に進めます。(「+」は無視されますが、適合していません。)
positionがinputの終端を超えている場合、エラーを返します。
positionが指している文字がASCII数字でない場合、エラーを返します。
コードポイントのシーケンスを収集し、positionを基にinputからASCII数字のシーケンスとして解釈します。その結果得られたシーケンスを10進数の整数として解釈し、valueにその整数を設定します。
signが「正」の場合はvalueを返し、それ以外の場合はvalueをゼロから引いた結果を返します。
文字列が1つ以上のASCII数字で構成されている場合、その文字列は有効な非負の整数です。
有効な非負の整数は、その数字列が表す10進数の値を表します。
非負の整数を解析するためのルールは、次のアルゴリズムで示されています。このアルゴリズムが呼び出されたときは、指定された順序でステップを実行し、値を返す最初のステップで中止しなければなりません。このアルゴリズムは、ゼロ、正の整数、またはエラーのいずれかを返します。
inputを解析中の文字列とします。
valueを、整数を解析するためのルールを使用してinputを解析した結果とします。
valueがエラーの場合、エラーを返します。
valueがゼロ未満の場合、エラーを返します。
valueを返します。
文字列が次の条件を満たす場合、それは有効な浮動小数点数です。
オプションとして、U+002D HYPHEN-MINUS文字(-)。
次のうち一つまたは両方が、この順序で含まれていること:
オプションとして:
U+0065 LATIN SMALL LETTER E文字(e)またはU+0045 LATIN CAPITAL LETTER E文字(E)。
オプションとして、U+002D HYPHEN-MINUS文字(-)またはU+002B PLUS SIGN文字(+)。
1つ以上のASCII数字の並び。
有効な浮動小数点数は、シグニフィカンドを10の指数に掛けた数を表します。シグニフィカンドは最初の数であり、それは10進数として解釈され(小数点と小数点後の数字を含む場合があります)、文字列全体がU+002D HYPHEN-MINUS文字(-)で始まり、数値がゼロでない場合はシグニフィカンドを負の数として解釈します。指数はEの後の数であり(Eと数の間にU+002D HYPHEN-MINUS文字(-)があり、数がゼロでない場合は負の数として解釈され、そうでない場合はEと数の間にU+002B PLUS SIGN文字(+)があっても無視されます)。Eがない場合、指数はゼロとして扱われます。
InfinityとNaN(非数)値は、有効な浮動小数点数ではありません。
有効な浮動小数点数の概念は、通常、著者が許可される内容を制限するためにのみ使用され、ユーザーエージェントの要件では浮動小数点数値を解析するためのルールが使用されます(例えば、max属性やprogress要素)。ただし、いくつかのケースでは、ユーザーエージェントの要件には文字列が有効な浮動小数点数であるかどうかのチェックが含まれる場合があります(例えば、値のサニタイズアルゴリズムやsrcset属性を解析するアルゴリズム)。
浮動小数点数としての数nの最良の表現は、ToString(n)を実行して得られる文字列です。抽象操作ToStringは一意に決定されません。特定の値に対して複数の可能な文字列がToStringから得られる場合、ユーザーエージェントは常にその値に対して同じ文字列を返さなければなりません(ただし、他のユーザーエージェントが使用する値と異なる場合があります)。
浮動小数点数値を解析するためのルールは、次のアルゴリズムで示されています。このアルゴリズムは、最初に値を返すステップで中止しなければなりません。このアルゴリズムは、数値またはエラーのいずれかを返します。
inputを解析中の文字列とします。
positionを、inputの開始位置を指すポインタとします。
valueに値1を設定します。
divisorに値1を設定します。
exponentに値1を設定します。
ASCIIの空白をスキップします。
positionがinputの終わりを超えている場合、エラーを返します。
positionが指している文字がU+002D HYPHEN-MINUS文字(-)である場合:
それ以外の場合、positionが指している文字がU+002B PLUS SIGN文字(+)である場合:
+」は無視されますが、準拠していません。)positionが指している文字がU+002E FULL STOP(.)であり、それがinputの最後の文字でなく、その次の文字がASCII数字である場合、valueをゼロに設定し、ステップ「Fraction」に進みます。
positionが指している文字がASCII数字でない場合、エラーを返します。
コードポイントのシーケンスを収集し、それをASCII数字として解釈し、そのシーケンスを10進数として解釈します。valueをその整数で掛けます。
Fraction:positionが指している文字がU+002E FULL STOP(.)である場合、次のサブステップを実行します:
もしpositionがU+0065 (e)またはU+0045 (E)を指している場合、次のようにします:
positionを次の文字に進めます。
もしpositionがinputの末尾を超えている場合は、conversionとラベル付けされたステップにジャンプします。
もしpositionがU+002D HYPHEN-MINUS文字(-)を指している場合:
もしpositionがinputの末尾を超えている場合は、conversionとラベル付けされたステップにジャンプします。
そうでなく、positionがU+002B PLUS SIGN文字(+)を指している場合:
もしpositionがinputの末尾を超えている場合は、conversionとラベル付けされたステップにジャンプします。
もしpositionがASCII digitでない場合は、conversionとラベル付けされたステップにジャンプします。
コードポイントのシーケンスを収集し、それがASCII digitsである場合、inputからpositionを与えて、その結果のシーケンスを10進数の整数として解釈します。exponentにその整数を掛けます。
valueを10のexponent乗で掛けます。
Conversion:Sを、有限のIEEE 754倍精度浮動小数点値(-0を除く)で構成された集合としますが、特別な値21024と-21024が追加されています。
rounded-valueをSの中でvalueに最も近い数とし、同じくらい近い値が2つある場合は、偶数のシグニフィカンドを持つ数を選びます。(この目的のために、特別な値21024と-21024は偶数のシグニフィカンドを持つと見なされます。)
rounded-valueが21024または-21024である場合、エラーを返します。
rounded-valueを返します。
寸法値を解析するためのルールは、次のアルゴリズムで示されています。呼び出されたとき、手順は指定された順序で実行され、値を返す最初のステップで中止しなければなりません。このアルゴリズムは、0.0以上の数値または失敗を返します。数値が返される場合、それはさらにパーセンテージまたは長さとして分類されます。
inputを解析中の文字列とします。
positionをinputの開始位置を指す位置変数とします。
ASCIIの空白をスキップします。
positionがinputの終わりを超えているか、positionが指しているコードポイントがASCII数字でない場合、失敗を返します。
コードポイントのシーケンスを収集し、それをASCII数字として解釈し、そのシーケンスを10進数として解釈します。valueをその数値とします。
positionがinputの終わりを超えている場合、valueを長さとして返します。
positionが指しているコードポイントがU+002E(.)である場合、次を実行します:
positionを1だけ進めます。
もしpositionがinputの末尾を超えているか、またはinput内のpositionにあるコードポイントがASCII digitでない場合は、現在の寸法値をvalue、input、およびpositionとともに返します。
divisorの値を1に設定します。
真の場合:
divisorに10を掛けます。
positionのinput内のコードポイントの値を、10進数の数字(0..9)として解釈し、それをdivisorで割った値をvalueに加えます。
positionを1だけ進めます。
もしpositionがinputの末尾を超えている場合は、valueを長さとして返します。
もしinput内のpositionにあるコードポイントがASCII digitでない場合は、中断します。
現在の寸法値をvalue、input、positionで返します。
現在の寸法値は、value、input、positionを用いて次のように決定されます:
ゼロでない寸法値を解析するためのルールは、次のアルゴリズムで示されています。呼び出されたとき、手順は指定された順序で実行され、値を返す最初のステップで中止しなければなりません。このアルゴリズムは、0.0より大きい数値またはエラーを返します。数値が返される場合、それはさらにパーセンテージまたは長さとして分類されます。
有効な浮動小数点数のリストは、U+002C コンマ文字で区切られた有効な浮動小数点数の集まりであり、それ以外の文字(例えばASCII空白)を含んではいけません。さらに、与えられる浮動小数点数の数や許容される値の範囲に制限があるかもしれません。
浮動小数点数リストを解析するためのルールは次の通りです:
inputを解析している文字列とします。
positionをinput内の文字列の先頭を指すポインタとして設定します。
numbersを空の浮動小数点数のリストとして設定します。このリストがこのアルゴリズムの結果となります。
コードポイントのシーケンスを収集し、それがASCIIホワイトスペース、U+002C コンマ、または U+003B セミコロン文字である場合、inputからpositionを指定して収集します。これにより、先頭の区切り文字をスキップします。
positionがinputの終わりを過ぎていない限り:
コードポイントのシーケンスを収集し、それがASCIIホワイトスペース、U+002C コンマ、U+003B セミコロン、ASCII数字、U+002E ピリオド、または U+002D ハイフンマイナス文字でない場合、inputからpositionを指定して収集します。これにより、先頭のゴミをスキップします。
コードポイントのシーケンスを収集し、それがASCIIホワイトスペース、U+002C コンマ、または U+003B セミコロン文字でない場合、inputからpositionを指定して収集し、unparsed numberに結果を設定します。
numberをunparsed numberを使用して解析した結果とします。解析ルールは浮動小数点数値の解析ルールに従います。
numberがエラーの場合、numberをゼロに設定します。
numberをnumbersに追加します。
コードポイントのシーケンスを収集し、それがASCIIホワイトスペース、U+002C コンマ、または U+003B セミコロン文字である場合、inputからpositionを指定して収集します。これにより、区切り文字をスキップします。
numbersを返します。
次元のリストを解析するためのルールは次の通りです。これらのルールは、パーセンテージ、相対的、絶対的のいずれかの単位を持つ、0個以上の数値と単位のペアのリストを返します。
raw inputを解析する文字列とします。
raw inputの最後の文字がU+002C コンマ文字(,)であれば、その文字をraw inputから削除します。
文字列raw inputをコンマで分割します。結果のトークンのリストをraw tokensとします。
resultを空の数値/単位ペアのリストとします。
各トークンがraw tokensにある間、以下のサブステップを実行します:
inputをトークンとします。
positionをinputへのポインタとし、初期状態では文字列の開始位置を指します。
valueを数値0とします。
unitをabsoluteとします。
positionがinputの終端を超えている場合、unitをrelativeに設定し、最後のサブステップにジャンプします。
positionの文字がASCII数字であれば、コードポイントのシーケンスを収集し、それがASCII数字からinputのpositionを指定して得られた場合、その結果のシーケンスを10進数の整数として解釈し、その整数でvalueを増加させます。
positionの文字がU+002E(.)の場合:
コードポイントのシーケンスを収集し、それがASCIIホワイトスペースとASCII数字である場合、inputのpositionを指定して収集し、sにその結果のシーケンスを設定します。
sからすべてのASCIIホワイトスペースを削除します。
sが空文字列でない場合、次を行います:
sの文字数をlengthとします(スペースが削除された後)。
fractionをsを10進整数として解釈し、その数を10lengthで割った結果とします。
valueをfractionで増加させます。
ASCIIホワイトスペースをスキップします。inputのpositionを指定して行います。
positionの文字がU+0025 パーセント記号(%)の場合、unitをpercentageに設定します。
それ以外の場合、positionの文字がU+002A アスタリスク(*)の場合、unitをrelativeに設定します。
valueによって示される数値とunitによって示される単位のペアをresultに追加します。
リストresultを返します。
以下のアルゴリズムでは、月month、年yearの月の日数は次のようになります:monthが1、3、5、7、8、10、12の場合は31日、monthが4、6、9、11の場合は30日、monthが2でyearが400で割り切れるか、4で割り切れるが100で割り切れない場合は29日、その他の場合は28日です。これはグレゴリオ暦の閏年を考慮しています。[GREGORIAN]
このセクションで定義されている日付と時刻の構文で使用されるASCII数字は、10進数を表します。
ここで説明する形式は対応するISO8601形式のサブセットを意図していますが、この仕様はISO8601よりもはるかに詳細な解析ルールを定義しています。したがって、実装者は以下に記述された解析ルールを実装する際に使用する日付解析ライブラリを慎重に検討することをお勧めします。ISO8601ライブラリは、日付や時刻を完全に同じ方法で解析しない場合があります。[ISO8601]
この仕様がプロレプティックグレゴリオ暦に言及する場合、それは現代のグレゴリオ暦を意味し、年1までさかのぼって外挿されます。プロレプティックグレゴリオ暦の日付、時にはプロレプティックグレゴリオ日付として明示的に言及されることもありますが、それはそのカレンダーが使用されていなかった時点(または場所)でもそのカレンダーを使用して記述されるものです。[GREGORIAN]
この仕様でグレゴリオ暦をワイヤフォーマットとして使用するのは、決定に関与した者の文化的偏見の結果としての任意の選択です。著者向けのセクションで日付、時刻、数字の形式、およびフォームコントロールのローカライズに関する実装ノートも参照してください。また、time要素も参照してください。
月は、年と月以外の日付情報およびタイムゾーン情報を持たない特定のプロレプティックグレゴリオ日付で構成されます。[GREGORIAN]
文字列が、次の順序で構成される場合、その文字列は年yearと月monthを表す有効な月文字列です:
月文字列を解析するためのルールは次のとおりです。これにより、年と月が返されるか、何も返されません。アルゴリズムが「失敗する」と言った場合、それはその時点で中止され、何も返されないことを意味します。
input文字列とpositionを与えられた場合の月コンポーネントを解析するためのルールは次のとおりです。これにより、年と月が返されるか、何も返されません。アルゴリズムが「失敗する」と言った場合、それはその時点で中止され、何も返されないことを意味します。
日付は、年、月、日で構成され、タイムゾーン情報を含まない特定のプロレプティックグレゴリオ日付で構成されます。[GREGORIAN]
文字列が、次の順序で構成される場合、その文字列は年year、月month、日dayを表す有効な日付文字列です:
日付文字列を解析するためのルールは次のとおりです。これにより、日付が返されるか、何も返されません。アルゴリズムが「失敗する」と言った場合、それはその時点で中止され、何も返されないことを意味します。
input文字列とpositionを与えられた場合の日付コンポーネントを解析するためのルールは次のとおりです。これにより、年、月、日が返されるか、何も返されません。アルゴリズムが「失敗する」と言った場合、それはその時点で中止され、何も返されないことを意味します。
年なし日付は、グレゴリオ暦の月とその月内の日で構成されますが、年は関連付けられていません。[GREGORIAN]
文字列が、次の順序で構成される場合、その文字列は月monthと日dayを表す有効な年なし日付文字列です:
言い換えれば、monthが「02」である場合、2月を意味し、その日が29日であっても、閏年であったかのように解釈されます。
年なし日付文字列を解析するためのルールは次のとおりです。これにより、月と日が返されるか、何も返されません。アルゴリズムが「失敗する」と言った場合、それはその時点で中止され、何も返されないことを意味します。
input文字列とpositionを与えられた場合の年なし日付コンポーネントを解析するためのルールは次のとおりです。これにより、月と日が返されるか、何も返されません。アルゴリズムが「失敗する」と言った場合、それはその時点で中止され、何も返されないことを意味します。
時間 は、時刻情報がなく、時間、分、秒、および秒の小数部分で構成されます。
文字列が次のコンポーネントを指定された順序で含む場合、それは時hour、分minute、秒secondを表す有効な時間文字列です:
secondコンポーネントは60または61にすることはできません。リープセコンドは表現できません。
時間文字列を解析するためのルールは次のとおりです。これにより、時間が返されるか、何も返されません。アルゴリズムが「失敗する」と言った場合、それはその時点で中止され、何も返されないことを意味します。
時間コンポーネントを解析するためのルールは次のとおりです。input文字列とpositionを与えられた場合、これにより、時間、分、秒が返されるか、何も返されません。アルゴリズムが「失敗する」と言った場合、それはその時点で中止され、何も返されないことを意味します。
コードポイントのシーケンスを収集し、それがASCII 数字であることを確認します。inputからpositionを基に収集します。収集したシーケンスがちょうど2文字でない場合は失敗します。それ以外の場合は、得られたシーケンスを10進整数として解釈し、その数値をhourとします。
positionがinputの終わりを超えているか、またはpositionの文字がU+003A コロン文字(:)でない場合は失敗します。それ以外の場合は、positionを1文字進めます。
コードポイントのシーケンスを収集し、それがASCII 数字であることを確認します。inputからpositionを基に収集します。収集したシーケンスがちょうど2文字でない場合は失敗します。それ以外の場合は、得られたシーケンスを10進整数として解釈し、その数値をminuteとします。
secondを0に設定します。
positionがinputの終わりを超えておらず、かつpositionの文字がU+003A(:)の場合、次のようにします:
positionをinputの次の文字に進めます。
positionがinputの終わりを超えている、またはinputの最後の文字である、またはpositionで始まる次の2文字が両方ともASCII 数字でない場合は失敗します。
コードポイントのシーケンスを収集し、それがASCII 数字またはU+002E ピリオド文字(.)であることを確認します。inputからpositionを基に収集します。収集したシーケンスが3文字である場合、または3文字を超えており3文字目がU+002E ピリオド文字でない場合、またはU+002E ピリオド文字が1つ以上含まれている場合は失敗します。それ以外の場合は、得られたシーケンスを10進数として解釈し(小数部分があるかもしれません)、その数値をsecondに設定します。
secondが範囲0 ≤ second < 60の数値でない場合は失敗します。
hour、minute、およびsecondを返します。
ローカルな日付と時刻は、特定のプロレプティックグレゴリオ暦日付(年、月、および日)と、タイムゾーンを含まない時間(時、分、秒、および秒の小数部)から構成されます。[GREGORIAN]
文字列が以下の順序で構成される場合、その文字列は日付と時刻を表す有効なローカルな日付と時刻の文字列です:
文字列が以下の順序で構成される場合、その文字列は日付と時刻を表す有効な正規化されたローカルな日付と時刻の文字列です:
ローカルな日付と時刻の文字列を解析するためのルールは次のとおりです。これにより、日付と時刻が返されるか、何も返されません。アルゴリズムが「失敗する」と言った場合、それはその時点で中止され、何も返されないことを意味します。
タイムゾーンオフセットは、符号付きの時間と分の数値から成ります。
文字列がタイムゾーンオフセットを表す有効なタイムゾーンオフセット文字列であるためには、次のいずれかでなければなりません:
U+005A ラテン大文字 Z 文字 (Z)、タイムゾーンが UTC の場合にのみ許可されます。
または、以下のコンポーネントを指定された順序で:
この形式では、タイムゾーンオフセットは -23:59 から +23:59 まで対応しています。現在実際に使用されているタイムゾーンのオフセット範囲は -12:00 から +14:00 までであり、実際のタイムゾーンの分コンポーネントは常に 00、30、または 45 です。ただし、タイムゾーンは政治的な問題として扱われるため、将来的に変更される可能性があります。
詳細については、以下のグローバル日付と時刻 セクションの使用ノートと例を参照してください。
タイムゾーンオフセット文字列を解析する ためのルールは次の通りです。これにより、タイムゾーンオフセットが返されるか、何も返されません。アルゴリズムが「失敗」と言った場合は、その時点で中止され、何も返されません。
input を解析中の文字列とします。
position を input へのポインタとして、文字列の先頭を指すようにします。
タイムゾーンオフセットコンポーネントを解析して timezonehours と timezoneminutes を取得します。これが何も返さなかった場合は失敗します。
もし position が input の終わりを越えていない場合、失敗します。
UTC から timezonehours 時間および timezoneminutes 分のタイムゾーンオフセットを返します。
タイムゾーンオフセットコンポーネントを解析する ためのルールは次の通りです。これはタイムゾーンの時間とタイムゾーンの分を返すか、何も返しません。アルゴリズムが「失敗」と言った場合は、その時点で中止され、何も返されません。
もし position にある文字が U+005A ラテン大文字 Z 文字 (Z) の場合:
timezonehours を 0 とします。
timezoneminutes を 0 とします。
position を次の文字に進めます。
そうでない場合、もし position にある文字が U+002B プラス記号 (+) または U+002D ハイフン記号 (-) の場合:
もし position にある文字が U+002B プラス記号 (+) の場合、sign を "positive" とします。そうでなければ、U+002D ハイフン記号 (-) であり、sign を "negative" とします。
position を次の文字に進めます。
コードポイントのシーケンスを収集する ASCII 数字 を収集します。s を収集したシーケンスとします。
s が正確に二文字の場合:
s を十進整数として解釈します。その数値を timezonehours とします。
もし position が input の終わりを越えているか、または position にある文字が U+003A コロン (:) でない場合、失敗します。そうでなければ、position を一文字進めます。
コードポイントのシーケンスを収集する ASCII 数字 を収集します。収集したシーケンスが正確に二文字でない場合、失敗します。そうでなければ、結果のシーケンスを十進整数として解釈します。その数値を timezoneminutes とします。
s が正確に四文字の場合:
s の最初の二文字を十進整数として解釈します。その数値を timezonehours とします。
s の最後の二文字を十進整数として解釈します。その数値を timezoneminutes とします。
そうでなければ、失敗します。
timezonehours が範囲 0 ≤ timezonehours ≤ 23 の数値でない場合、失敗します。
sign が "negative" の場合、timezonehours を反転させます。
timezoneminutes が範囲 0 ≤ timezoneminutes ≤ 59 の数値でない場合、失敗します。
sign が "negative" の場合、timezoneminutes を反転させます。
そうでなければ、失敗します。
timezonehours と timezoneminutes を返します。
グローバル日付と時刻 は、特定の先験的グレゴリオ暦の日付(年、月、日を含む)と、時間(時、分、秒、秒の小数部分を含む)、そして時差を表すサイン付きの時間と分からなる。
文字列が次の要素で構成されている場合、それは日付、時刻、および時差を表す有効なグローバル日付と時刻の文字列です:
UTCの形成前の時刻は、UT1(0°経度での地球太陽時間)で表現され解釈されなければならず、UTC(SI秒で刻まれるUT1の近似値)ではありません。タイムゾーンの形成前の時刻は、UT1時刻として明示的なタイムゾーンとともに、グリニッジ、ロンドンで観測された時刻との差を近似した形で表現し解釈されなければなりません。
次は、有効なグローバル日付と時刻の文字列として書かれた日付の例です。
0037-12-13 00:00Z"
1979-10-14T12:00:00.001-04:00"
8592-01-01T02:09+02:09"
これらの日付について注目すべき点は次のとおりです:
T" がスペースに置き換えられる場合、それは単一のスペース文字でなければなりません。"2001-12-21
12:00Z"(コンポーネント間に2つのスペースがある)は正しく解析されません。
グローバル日付と時刻の文字列を解析する ルールは次のとおりです。これにより、UTCの時刻と、ラウンドトリップまたは表示目的のための関連する時差情報が返されるか、何も返されません。アルゴリズムが「失敗した」と言った場合、その時点で中止され、何も返されません。
input を解析する文字列とします。
position を input 内のポインタとし、初期状態で文字列の開始位置を指します。
日付コンポーネントを解析する ことで、year、month、および day を取得します。これが何も返さない場合は、失敗します。
position が input の末尾を超えているか、position の文字が U+0054 ラテン大文字 T 文字 (T) または U+0020 スペース文字でない場合は、失敗します。それ以外の場合、position を1文字進めます。
時刻コンポーネントを解析する ことで、hour、minute、および second を取得します。これが何も返さない場合は、失敗します。
position が input の末尾を超えている場合は、失敗します。
時差コンポーネントを解析する ことで、timezonehours と timezoneminutes を取得します。これが何も返さない場合は、失敗します。
position が input の末尾を超えていない場合は、失敗します。
time を、year 年、month 月、day 日、hour 時、minute 分、second 秒の時刻から、timezonehours 時間と timezoneminutes 分を引いた瞬間とします。その瞬間はUTCタイムゾーンでの瞬間です。
timezone を timezonehours 時間と timezoneminutes 分のUTCからの偏差とします。
time と timezone を返します。
週 とは、週番号と、月曜日から始まる7日間の期間を表す週番号で構成されます。このカレンダーシステムでは、各週年には以下に定義されたように52または53のそのような7日間の期間があります。1969年12月29日(1969-12-29)のグレゴリオ暦の日付で始まる7日間の期間は、1970年の週年で週番号1として定義されます。連続する週は順番に番号付けされます。週年内の番号1の週の前の週は、前の週年の最後の週であり、その逆も同様です。 [GREGORIAN]
週年番号がyearの週年が53週間を持つ場合、それは以下のいずれかに対応します: 先験的グレゴリオ暦のyear年の最初の日(1月1日)が木曜日であるか、またはyear年の先験的グレゴリオ暦の最初の日(1月1日)が水曜日であり、かつyearが400で割り切れるか、または100で割り切れない4で割り切れる数である場合。その他の週年は52週間です。
53週間の週年の最終日の週番号は53であり、52週間の週年の最終日の週番号は52です。
特定の日の週年番号は、その日を含む年の番号と異なる場合があります。このHTMLのバージョンでは、週年yの最初の週は、グレゴリオ暦の年yの最初の木曜日を含む週です。
現代の目的では、ここで定義された週は、ISO 8601で定義されたISO週と同等です。 [ISO8601]
文字列が週年yearと週weekを表す有効な週文字列であるためには、次のコンポーネントで構成されている必要があります:
週文字列を解析するルールは次のとおりです。これにより、週年番号と週番号が返されるか、何も返されません。アルゴリズムが「失敗した」と言った場合、その時点で中止され、何も返されません。
input を解析する文字列とします。
position を input 内のポインタとし、初期状態で文字列の開始位置を指します。
コードポイントのシーケンスを収集する、position でのinputからASCII数字を収集します。収集したシーケンスが4文字未満の場合、失敗します。そうでなければ、そのシーケンスを10進整数として解釈します。その数値をyearとします。
もしyearがゼロより大きい数でない場合、失敗します。
positionがinputの末尾を超えているか、positionの文字がU+002D ハイフン (-) 文字でない場合、失敗します。そうでなければ、positionを1文字進めます。
positionがinputの末尾を超えているか、positionの文字がU+0057 ラテン大文字 W 文字 (W) でない場合、失敗します。そうでなければ、positionを1文字進めます。
コードポイントのシーケンスを収集する、positionでのinputからASCII数字を収集します。収集したシーケンスが正確に2文字でない場合、失敗します。そうでなければ、そのシーケンスを10進整数として解釈します。その数値をweekとします。
maxweekを年yearの最終日の週番号とします。
もしweekが範囲1 ≤ week ≤ maxweekの数でない場合、失敗します。
positionがnot inputの末尾を超えていない場合、失敗します。
週年番号yearと週番号weekを返します。
デュレーションは、秒数の数で構成されます。
月と秒は比較できません(1か月は正確な秒数ではなく、その長さは起算日によって異なるため)、この仕様で定義されたデュレーションには月(または12か月に相当する年)を含むことはできません。特定の秒数を示すデュレーションのみが説明できます。
文字列がデュレーション tを表す有効なデュレーション文字列である場合、それが以下のいずれかで構成されている必要があります:
U+0050 ラテン大文字 P 文字のリテラルの後に、次のサブコンポーネントが1つ以上、指定された順序で続き、日、時間、分、秒の数がtの秒数と一致する:
1つ以上のASCII数字の後に、U+0044 ラテン大文字 D 文字が続き、日数を表します。
U+0054 ラテン大文字 T 文字の後に、次のサブコンポーネントが1つ以上、指定された順序で続く:
これは、この仕様で定義されたいくつかの他の日付および時間に関連するマイクロシンタックスの1つとして、ISO 8601で定義された形式の1つに基づいています。[ISO8601]
1つ以上の期間時間コンポーネント、それぞれ異なる期間時間コンポーネントスケールを持ち、任意の順序で配置され、表された秒数の合計がtの秒数と等しくなる。
期間時間コンポーネントは、次のコンポーネントで構成される文字列です:
ゼロ個以上のASCII空白文字。
1つ以上のASCII数字、指定された期間時間コンポーネントスケールによって秒数を表す。
指定された期間時間コンポーネントスケールが1(すなわち、単位が秒である)場合、オプションで、U+002E ピリオド文字(.)の後に、1、2、または3つのASCII数字、秒の小数部を表します。
ゼロ個以上のASCII空白文字。
次のいずれかの文字、期間時間コンポーネントの数値部分で使用される時間単位の期間時間コンポーネントスケールを表します:
ゼロ個以上のASCII空白文字。
これは、ISO 8601 の形式のいずれにも基づいていません。ISO 8601 の期間形式に対するより人間にとって読みやすい代替手段として意図されています。
期間文字列を解析するルールは以下の通りです。これにより、期間が返されるか、何も返されません。アルゴリズムが「失敗」と言った場合、その時点で中止され、何も返されないことを意味します。
inputを解析する文字列とします。
positionをinput内のポインタとし、最初は文字列の先頭を指します。
months、seconds、およびcomponent countをすべてゼロに設定します。
M-disambiguatorをminutesに設定します。
このフラグのもう一つの値はmonthsです。これはISO8601の期間において「M」単位を区別するために使用されます。この単位は月と分の両方を表します。月は許可されていませんが、将来的な互換性のため、または他のコンテキストで有効であるISO8601の期間を誤解しないように解析されます。
ASCII空白文字をスキップして、positionが指す位置のinput内を確認します。
positionがinputの終端を過ぎている場合、失敗します。
positionが指すinput内の文字がU+0050 LATIN CAPITAL LETTER Pである場合、positionを次の文字に進め、M-disambiguatorをmonthsに設定し、ASCII空白文字をスキップしてpositionが指す位置のinput内を確認します。
ループ開始:
unitsを未定義にします。これは次のいずれかの値に設定されます: years、months、weeks、days、hours、minutes、およびseconds。
next characterを未定義にします。これはinputから文字を処理するために使用されます。
positionがinputの終端を過ぎている場合、ループを終了します。
positionが指すinput内の文字がU+0054 LATIN CAPITAL LETTER Tである場合、positionを次の文字に進め、M-disambiguatorをminutesに設定し、ASCII空白文字をスキップしてpositionが指す位置のinput内を確認し、処理を続行します。
next characterをpositionが指すinput内の文字に設定します。
next characterがU+002E FULL STOP (.)である場合、Nをゼロに設定します。(positionを進めないでください。それは後で処理されます。)
そうでない場合、next characterがASCII数字である場合、コードポイントのシーケンスを収集し、positionが指す位置のinputからそれらを収集し、その結果のシーケンスを10進数の整数として解釈し、Nにその数値を設定します。
それ以外の場合、next characterが数字の一部ではない場合、失敗します。
positionがinputの終端を過ぎている場合、失敗します。
next characterをpositionが指すinput内の文字に設定し、今回はpositionを次の文字に進めます。(以前next characterがU+002E FULL STOP (.)だった場合、今回もその文字のままです。)
next characterがU+002E (.)である場合、次のようにします:
コードポイントのシーケンスを収集し、positionが指す位置のinputからそれらを収集します。sを結果のシーケンスに設定します。
sが空文字列の場合、失敗します。
lengthをsの文字数に設定します。
fractionをsを10進数の整数として解釈した結果とし、その数値を10lengthで割ります。
Nをfractionで増加させます。
ASCII空白文字をスキップして、positionが指す位置のinput内を確認します。
positionがinputの終端を過ぎている場合、失敗します。
next characterをpositionが指すinput内の文字に設定し、positionを次の文字に進めます。
next characterがU+0053 LATIN CAPITAL LETTER SまたはU+0073 LATIN SMALL LETTER Sのどちらでもない場合、失敗します。
unitsをsecondsに設定します。
それ以外の場合:
next characterがASCII空白文字である場合、ASCII空白文字をスキップしてpositionが指す位置のinput内を確認し、next characterをpositionが指すinput内の文字に設定し、positionを次の文字に進めます。
next characterがU+0059 LATIN CAPITAL LETTER YまたはU+0079 LATIN SMALL LETTER Yである場合、unitsをyearsに設定し、M-disambiguatorをmonthsに設定します。
next characterがU+004D LATIN CAPITAL LETTER MまたはU+006D LATIN SMALL LETTER Mであり、M-disambiguatorがmonthsである場合、unitsをmonthsに設定します。
next characterがU+0057 LATIN CAPITAL LETTER WまたはU+0077 LATIN SMALL LETTER Wである場合、unitsをweeksに設定し、M-disambiguatorをminutesに設定します。
next characterがU+0044 LATIN CAPITAL LETTER DまたはU+0064 LATIN SMALL LETTER Dである場合、unitsをdaysに設定し、M-disambiguatorをminutesに設定します。
next characterがU+0048 LATIN CAPITAL LETTER HまたはU+0068 LATIN SMALL LETTER Hである場合、unitsをhoursに設定し、M-disambiguatorをminutesに設定します。
next characterがU+004D LATIN CAPITAL LETTER MまたはU+006D LATIN SMALL LETTER Mであり、M-disambiguatorがminutesである場合、unitsをminutesに設定します。
next characterがU+0053 LATIN CAPITAL LETTER SまたはU+0073 LATIN SMALL LETTER Sである場合、unitsをsecondsに設定し、M-disambiguatorをminutesに設定します。
それ以外の場合、next characterが上記のいずれでもない場合、失敗します。
component countをインクリメントします。
multiplierを1に設定します。
unitsがyearsである場合、multiplierに12を掛け、unitsをmonthsに設定します。
unitsがmonthsである場合、Nとmultiplierの積をmonthsに加えます。
それ以外の場合:
unitsがweeksである場合、multiplierに7を掛け、unitsをdaysに設定します。
unitsがdaysである場合、multiplierに24を掛け、unitsをhoursに設定します。
unitsがhoursである場合、multiplierに60を掛け、unitsをminutesに設定します。
unitsがminutesである場合、multiplierに60を掛け、unitsをsecondsに設定します。
強制的に、unitsはsecondsに設定されます。Nとmultiplierの積をsecondsに加えます。
ASCII空白文字をスキップして、positionが指す位置のinput内を確認します。
component countがゼロの場合、失敗します。
monthsがゼロでない場合、失敗します。
seconds秒で構成された期間を返します。
文字列が任意の時間を含む有効な日付文字列であるためには、それが次のいずれかである必要があります。
日付または時間の文字列を解析するためのルールは以下の通りです。アルゴリズムは日付、時間、世界日付および時間、もしくは何も返しません。アルゴリズムが「失敗する」と述べた場合、それはその時点で中止され、何も返されないことを意味します。
input を解析中の文字列とします。
position を input 内のポインタとし、初期状態では文字列の開始位置を指します。
position と同じ位置に start position を設定します。
date present フラグと time present フラグを true に設定します。
日付コンポーネントを解析する ことで year、month、day を取得します。これが失敗した場合、date present フラグを false に設定します。
もし date present が true であり、position が input の終端を超えていない場合、および position の文字が U+0054 ラテン大文字 T 文字(T)または U+0020 スペース文字である場合、position を input 内の次の文字に進めます。
それ以外の場合、もし date present が true であり、かつ position が input の終端を超えているか、または position の文字が U+0054 ラテン大文字 T 文字でも U+0020 スペース文字でもない場合、time present フラグを false に設定します。
それ以外の場合、もし date present が false であれば、position を start position と同じ位置に戻します。
もし time present フラグが true であれば、時間コンポーネントを解析する ことで hour、minute、second を取得します。これが何も返さない場合、失敗します。
もし date present フラグと time present フラグが両方とも true であるにもかかわらず、position が input の終端を超えている場合、失敗します。
もし date present フラグと time present フラグが両方とも true であれば、タイムゾーンオフセットコンポーネントを解析する ことで timezonehours と timezoneminutes を取得します。これが何も返さない場合、失敗します。
もし position が input の終端を超えていない場合、失敗します。
もし date present フラグが true で time present フラグが false であれば、date を year、month、day からなる日付とし、date を返します。
それ以外の場合、もし time present フラグが true で date present フラグが false であれば、time を hour、minute、second からなる時間とし、time を返します。
それ以外の場合、time を year、month、day、hour、minute、second からなる瞬間とし、これに timezonehours 時間と timezoneminutes 分を引いた、UTC タイムゾーンでの瞬間とし、timezone を UTC から timezonehours 時間および timezoneminutes 分とし、time と timezone を返します。
シンプルな色は、'srgb'カラースペース内の赤、緑、青のコンポーネントをそれぞれ表す0から255までの範囲の3つの8ビット数で構成されます。
文字列が有効なシンプルな色であるためには、正確に7文字で構成されており、最初の文字がU+0023 番号記号文字(#)で、残りの6文字がすべてASCII 16進数字であり、最初の2桁が赤のコンポーネント、中間の2桁が緑のコンポーネント、最後の2桁が16進数で青のコンポーネントを表している必要があります。
文字列が有効な小文字のシンプルな色であるためには、それが有効なシンプルな色であり、U+0041からU+0046の範囲の文字(ラテン大文字AからF)を使用していない必要があります。
シンプルな色の値を解析するためのルールは、次のアルゴリズムで与えられます。呼び出されたとき、ステップは与えられた順に従い、値を返す最初のステップで中止する必要があります。このアルゴリズムはシンプルな色またはエラーを返します。
inputを解析する文字列とします。
もしinputが正確に7文字でない場合、エラーを返します。
もしinputの最初の文字がU+0023 番号記号文字(#)でない場合、エラーを返します。
もしinputの最後の6文字がすべてASCII 16進数字でない場合、エラーを返します。
resultをシンプルな色とします。
2番目と3番目の文字を16進数として解釈し、その結果をresultの赤のコンポーネントとします。
4番目と5番目の文字を16進数として解釈し、その結果をresultの緑のコンポーネントとします。
6番目と7番目の文字を16進数として解釈し、その結果をresultの青のコンポーネントとします。
resultを返します。
シンプルな色の値をシリアル化するためのルールは、次のアルゴリズムで与えられます。
resultを1つのU+0023 番号記号文字(#)から成る文字列とします。
赤、緑、青のコンポーネントを順に2桁の16進数に変換し、必要に応じてゼロでパディングし、これらの数値をresultに赤、緑、青の順で追加します。
resultを返します。それは有効な小文字のシンプルな色になります。
一部の古いレガシー属性は、レガシーな色の値を解析するためのルールを使用して、より複雑な方法で色を解析します。これらは次のアルゴリズムで与えられます。呼び出されたとき、ステップは与えられた順に従い、値を返す最初のステップで中止する必要があります。このアルゴリズムはシンプルな色またはエラーを返します。
inputを解析する文字列とします。
もしinputが空文字列であれば、エラーを返します。
もしinputが文字列「transparent」に対してASCII 大文字小文字を区別しない一致である場合、エラーを返します。
もしinputが名前付き色のいずれかに対してASCII 大文字小文字を区別しない一致である場合、そのキーワードに対応するシンプルな色を返します。[CSSCOLOR]
もしinputのコードポイントの長さが4であり、inputの最初の文字がU+0023(#)であり、inputの最後の3文字がすべてASCII 16進数字である場合:
resultをシンプルな色とします。
inputの2番目の文字を16進数の数字として解釈し、その結果をresultの赤のコンポーネントにします。その数字を17倍します。
inputの3番目の文字を16進数の数字として解釈し、その結果をresultの緑のコンポーネントにします。その数字を17倍します。
inputの4番目の文字を16進数の数字として解釈し、その結果をresultの青のコンポーネントにします。その数字を17倍します。
resultを返します。
input内のU+FFFFを超えるコードポイント(つまり、基本多言語面に含まれない文字)を「00」という2文字の文字列に置き換えます。
もしinputのコードポイントの長さが128を超える場合、inputを最初の128文字だけ残して切り詰めます。
もしinputの最初の文字がU+0023 番号記号文字(#)であれば、それを削除します。
input内のASCII 16進数字でない文字をU+0030 数字ゼロ(0)文字に置き換えます。
もしinputのコードポイントの長さがゼロまたは3の倍数でない場合、U+0030 数字ゼロ(0)文字をinputに追加します。
inputを等しいコードポイントの長さの3つの文字列に分割し、3つのコンポーネントを取得します。lengthをこれらのコンポーネントすべてが持つコードポイントの長さ(inputのコードポイントの長さの3分の1)とします。
もしlengthが8を超える場合、各コンポーネントの先頭のlength-8文字を削除し、lengthを8とします。
もしlengthが2を超える間、各コンポーネントの最初の文字がU+0030 数字ゼロ(0)文字である場合、その文字を削除し、lengthを1減らします。
もしlengthがまだ2を超える場合、各コンポーネントを切り詰め、最初の2文字だけを残します。
resultをシンプルな色とします。
最初のコンポーネントを16進数として解釈し、その結果をresultの赤のコンポーネントとします。
2番目のコンポーネントを16進数として解釈し、その結果をresultの緑のコンポーネントとします。
3番目のコンポーネントを16進数として解釈し、その結果をresultの青のコンポーネントとします。
resultを返します。
2D グラフィックスコンテキストは、透明度も扱う別の色の構文を持っています。
スペースで区切られたトークンのセットは、1つ以上のASCII空白文字で区切られたゼロ個以上の単語(トークンと呼ばれる)を含む文字列です。単語は、1つ以上の文字からなる任意の文字列で、ASCII空白文字を含まないものとします。
スペースで区切られたトークンのセットを含む文字列には、先頭または末尾にASCII空白文字が含まれている場合があります。
順序のない一意のスペースで区切られたトークンのセットは、トークンが重複していないスペースで区切られたトークンのセットです。
順序がある一意のスペースで区切られたトークンのセットは、トークンが重複していないが、トークンの順序に意味があるスペースで区切られたトークンのセットです。
スペースで区切られたトークンのセットには、許可された値の定義済みセットがある場合があります。許可された値のセットが定義されている場合、トークンはその許可された値のリストからのものでなければなりません。その他の値は非準拠です。許可された値のセットが提供されていない場合は、すべての値が準拠とされます。
スペースで区切られたトークンのセットにおいてトークンを比較する方法(例: 大文字小文字を区別するかどうか)は、セットごとに定義されます。
コンマ区切りのトークンのセットは、ゼロ個以上のトークンを含む文字列で、各トークンは次のトークンとU+002C COMMA文字(,)で区切られています。トークンはゼロ個以上の文字からなる任意の文字列であり、ASCII空白文字で始まったり終わったりせず、U+002C COMMA文字(,)を含まないものとし、任意でASCII空白文字で囲まれている場合があります。
例えば、文字列「 a ,b,,d d 」は、4つのトークン「a」、「b」、「」(空の文字列)、および「d
d」で構成されます。各トークンの前後の空白はトークンの一部とはみなされず、空の文字列もトークンになり得ます。
コンマ区切りのトークンのセットには、有効なトークンを構成するものに関するさらなる制限が課される場合があります。そのような制限が定義されている場合、トークンはすべてその制限に適合しなければなりません。その他の値は非準拠です。もしそのような制限が指定されていない場合、すべての値が準拠となります。
type型の要素への有効なハッシュ名参照は、U+0023
番号記号文字(#)で始まり、そのtype型の要素のname属性の値と完全に一致する文字列で構成されます。その要素は同じツリー内に存在します。
type型の要素へのハッシュ名参照を解析するためのルールは、コンテキストノードscopeが与えられた場合、以下の通りです。
解析されている文字列にU+0023 番号記号文字が含まれていない場合、または文字列内の最初の番号記号文字が文字列の最後の文字である場合、nullを返します。
sを、解析されている文字列内の最初のU+0023 番号記号文字の直後の文字からその文字列の終わりまでの文字列とします。
scopeのツリー内で、ツリー順にsの値を持つidまたはname属性を持つ最初のtype型の要素を返します。該当する要素がない場合はnullを返します。
id属性は解析時に考慮されますが、値が有効なハッシュ名参照であるかどうかを決定する際には使用されません。つまり、idに基づいて要素を参照するハッシュ名参照は、(その要素に同じ値のname属性がある場合を除いて)準拠エラーです。
文字列が有効なメディアクエリリストであるためには、それがMedia
Queriesの<media-query-list>生成規則に一致する必要があります。[MQ]
文字列がユーザーの環境に一致するためには、それが空の文字列、ASCII空白文字のみで構成された文字列、またはMedia Queriesで定義されたユーザーの環境に一致するメディアクエリリストである必要があります。[MQ]
一意の内部値は、シリアライズ可能で、値で比較可能であり、スクリプトに公開されない値です。
新しい一意の内部値を作成するには、このアルゴリズムで以前に返されたことのない一意の内部値を返します。
文字列が有効な非空のURLであるためには、それが有効なURL文字列であり、かつ空文字列ではない必要があります。
文字列がスペースで囲まれた可能性のある有効なURLであるためには、それから先頭および末尾のASCII空白文字を取り除いた後に、それが有効なURL文字列である必要があります。
文字列がスペースで囲まれた可能性のある有効な非空のURLであるためには、それから先頭および末尾のASCII空白文字を取り除いた後に、それが有効な非空のURLである必要があります。
この仕様では、about:legacy-compatというURLを予約済みで解決不可能なURLとして定義していますが、XMLツールとの互換性を確保するためにDOCTYPEにおいてHTML文書で使用されます。[ABOUT]
この仕様では、about:html-kindというURLを予約済みで解決不可能なURLとして定義していますが、これはメディアトラックの種類を識別するために使用されます。[ABOUT]
この仕様では、about:srcdocというURLを予約済みで解決不可能なURLとして定義していますが、これはURLがiframeのsrcdoc文書として使用されます。[ABOUT]
DocumentオブジェクトdocumentのフォールバックベースURLは、次の手順を実行して取得されるURLレコードです:
もしdocumentがiframeのsrcdoc文書である場合:
確認: documentのaboutベースURLがnullでないことを確認します。
documentのaboutベースURLを返します。
もしdocumentのURLがabout:blankに一致し、かつdocumentのaboutベースURLがnullでない場合、documentのaboutベースURLを返します。
documentのURLを返します。
Documentオブジェクトの文書ベースURLは、次の手順を実行して取得されるURLレコードです:
もしbase要素がなく、そのhref属性がDocumentにない場合、DocumentのフォールバックベースURLを返します。
URLがabout:blankに一致するためには、そのスキームが「about」であり、そのパスが単一の文字列「blank」を含み、そのユーザー名およびパスワードが空文字列であり、そのホストがnullである必要があります。
このようなURLのクエリおよびフラグメントはnullでない可能性があります。例えば、URLレコードは「about:blank?foo#bar」を解析して作成されたabout:blankに一致します。
URLがabout:srcdocに一致するためには、そのスキームが「about」であり、そのパスが単一の文字列「srcdoc」を含み、そのクエリがnullであり、そのユーザー名およびパスワードが空文字列であり、そのホストがnullである必要があります。
about:srcdocがURLのクエリをnullにする理由は、iframe srcdocドキュメントのURLに非nullのクエリを持つことができないためです。これは、URLの集合のうち、about:srcdocに一致するものは、そのフラグメントのみが異なるからです。
URLを解析することは、文字列を受け取り、それが表すURLレコードを取得するプロセスです。このプロセスはURLで定義されていますが、HTML標準ではベースURLやエンコーディングを抽象化するためのいくつかのラッパーが定義されています。[URL]
新しいAPIのほとんどはURLを解析するを使用します。古いAPIやHTML要素は、エンコーディングを考慮してURLを解析するを使用する理由があるかもしれません。カスタムベースURLが必要な場合やベースURLが不要な場合は、URLパーサーを直接使用することももちろん可能です。
urlという文字列を、Documentオブジェクトまたは環境設定オブジェクトであるenvironmentに対してURLを解析するためには、次のステップを実行します。これらは失敗またはURLを返します。
もしenvironmentがDocumentオブジェクトであれば、baseURLをenvironmentのベースURLとし、それ以外の場合はenvironmentのAPIベースURLとします。
baseURLを使用して、urlに対してURLパーサーを適用した結果を返します。
urlという文字列を、Documentオブジェクトまたは環境設定オブジェクトであるenvironmentに対してエンコーディングを考慮してURLを解析するためには、次のステップを実行します。これらは失敗またはURLを返します。
encodingをUTF-8とします。
もしenvironmentがDocumentオブジェクトであれば、encodingをenvironmentの文字エンコーディングに設定します。
それ以外の場合、もしenvironmentの関連グローバルオブジェクトがWindowオブジェクトであれば、encodingをenvironmentの関連グローバルオブジェクトの関連するDocumentの文字エンコーディングに設定します。
もしenvironmentがDocumentオブジェクトであれば、baseURLをenvironmentのベースURLとし、それ以外の場合はenvironmentのAPIベースURLとします。
baseURLとencodingを使用して、urlに対してURLパーサーを適用した結果を返します。
urlという文字列を、Documentオブジェクトまたは環境設定オブジェクトであるenvironmentに対してエンコーディングを考慮してURLを解析およびシリアル化するためには、次のステップを実行します。これらは失敗または文字列を返します。
urlを、environmentに対してエンコーディングを考慮してURLを解析することによって得られる結果とします。
もしurlが失敗であれば、失敗を返します。
urlに対してURLシリアライザーを適用した結果を返します。
文書の文書ベースURLが変更された場合、その文書内のすべての要素はベースURLの変更によって影響を受けることになります。
以下はベースURL変更手順であり、要素がベースURLの変更によって影響を受ける(DOMで定義されているように)際に実行されます:
もし、ハイパーリンクによって識別されるURLがユーザーに表示されている場合、またはそのURLから得られたデータが表示に影響を与えている場合、href属性の値は、要素のノード文書に対して再解析され、適切にUIが更新されるべきです。
例えば、CSSの:link/:visited疑似クラスが影響を受ける可能性があります。
ハイパーリンクにping属性があり、そのURL(s)がユーザーに表示されている場合、ping属性のトークンは要素のノード文書に対して再解析され、適切にUIが更新されるべきです。
q、blockquote、ins、またはdel要素であり、cite属性を持つ場合
もし、cite属性によって識別されるURLがユーザーに表示されている場合、またはそのURLから得られたデータが表示に影響を与えている場合、cite属性の値は要素のノード文書に対して再解析され、適切にUIが更新されるべきです。
要素は直接影響を受けません。
例えば、ベースURLを変更しても、img要素によって表示される画像には影響しませんが、その後のスクリプトからのsrcIDL属性のアクセスでは、表示されている画像に対応しなくなる可能性がある新しい絶対URLが返されます。
レスポンスのタイプが"basic"、"cors"、または"default"である場合、そのレスポンスはCORS同一オリジンです。[FETCH]
レスポンスのタイプが"opaque"または"opaqueredirect"である場合、そのレスポンスはCORSクロスオリジンです。
レスポンスの不安全なレスポンスは、もし存在するならその内部レスポンスであり、そうでない場合はレスポンス自体です。
url、destination、corsAttributeState、およびオプションの同一オリジンフォールバックフラグが与えられた場合に潜在的なCORSリクエストを作成するには、次のステップを実行します:
corsAttributeStateがNo
CORSである場合、modeを"no-cors"とし、それ以外の場合は"cors"とします。
もし同一オリジンフォールバックフラグが設定されていて、modeが"no-cors"である場合、modeを"same-origin"に設定します。
credentialsModeを"include"とします。
corsAttributeStateがAnonymousである場合、credentialsModeを"same-origin"に設定します。
requestを新しいリクエストとし、そのURLをurl、宛先をdestination、モードをmode、認証モードをcredentialsModeとし、URL資格情報フラグを設定します。
リソースのContent-Typeメタデータは、MIME Sniffingの要件に従って取得および解釈されなければなりません。[MIMESNIFF]
リソースの計算されたMIMEタイプは、MIME Sniffingで示された要件に従って求めなければなりません。[MIMESNIFF]
画像を特定するための規則、リソースがテキストかバイナリかを区別するための規則、および音声および動画を特定するための規則もMIME Sniffingで定義されています。これらの規則は、結果としてMIMEタイプを返します。[MIMESNIFF]
MIME Sniffingの規則は正確に遵守することが重要です。ユーザーエージェントがサーバーの期待とは異なるヒューリスティックでコンテンツタイプを検出する場合、セキュリティ問題が発生する可能性があります。詳細はMIME Sniffingを参照してください。[MIMESNIFF]
meta要素から文字エンコーディングを抽出する文字列sが与えられた場合のmeta要素から文字エンコーディングを抽出するためのアルゴリズムは以下の通りです。このアルゴリズムは、文字エンコーディングまたは何も返さない場合があります。
positionをsのポインタとし、初期位置を文字列の先頭に設定します。
ループ: positionの後にs内で最初に現れる7文字を探し、その文字列が"charset"とASCII大文字小文字を区別しない一致であるか確認します。そのような一致が見つからなかった場合、何も返さず終了します。
"charset"の後に続くASCII空白文字をスキップします(存在しない場合もあります)。
次の文字がU+003D EQUALS SIGN(=)でない場合、positionを次の文字の直前に移動し、ループラベルのステップに戻ります。
等号の後に続くASCII空白文字をスキップします(存在しない場合もあります)。
次の文字を以下のように処理します:
このアルゴリズムはHTTP仕様書内のものとは異なります(例えば、HTTPではシングルクォートの使用が許可されておらず、このアルゴリズムがサポートしていないバックスラッシュエスケープ機構のサポートが必要です)。このアルゴリズムは、歴史的にはHTTPに関連する文脈で使用されていましたが、実装によってサポートされる構文はしばらく前に分岐しました。[HTTP]
CORS設定属性は、次のキーワードと状態を持つ列挙属性です:
| キーワード | 状態 | 簡単な説明 |
|---|---|---|
anonymous
| Anonymous | 要素のリクエストは、そのモードが"cors"に設定され、その認証モードが"same-origin"に設定されます。
|
| (空の文字列) | ||
use-credentials
| Use Credentials | 要素のリクエストは、そのモードが"cors"に設定され、その認証モードが"include"に設定されます。
|
属性の欠落値のデフォルトはNo CORS状態であり、無効値のデフォルトはAnonymous状態です。リフレクションの目的のために、標準キーワードはAnonymous状態に対応するanonymousキーワードです。
CORS設定属性により管理されるフェッチの大部分は、潜在的なCORSリクエストを作成するアルゴリズムを通じて実行されます。
リクエストのモードが常に"cors"であるよりモダンな機能に対しては、特定のCORS設定属性が再利用され、わずかに異なる意味を持つようになります。これにより、リクエストのリクエストの認証モードのみに影響を与えるようになります。この変換を行うために、特定のCORS設定属性に対してCORS設定属性認証モードを次の状態に応じて定義します:
same-origin"
include"
リファラーポリシー属性は列挙属性です。空の文字列を含む各リファラーポリシーがこの属性のキーワードであり、同名の状態にマッピングされます。
この属性の欠落値のデフォルトおよび無効値のデフォルトはいずれも空の文字列状態です。
これらの状態がさまざまなフェッチの処理モデルに与える影響については、この仕様全体、Fetch、およびReferrer Policyでより詳細に定義されています。[FETCH] [REFERRERPOLICY]
特定のフェッチに対してどの処理モデルが使用されるかに寄与するシグナルはいくつかありますが、リファラーポリシー属性はその一部に過ぎません。一般的に、これらのシグナルが処理される順序は以下の通りです:
最初に、noreferrerリンクタイプの存在を確認します。
次に、リファラーポリシー属性の値を確認します。
最後に、Referrer-PolicyHTTPヘッダーを確認します。
すべての最新エンジンでサポートされています。
nonce
コンテンツ属性は、暗号化された nonce(「一度だけ使用される番号」)を表し、特定のフェッチが許可されるかどうかを判断するために Content Security Policy
によって使用されます。値はテキストです。[CSP]
nonce コンテンツ属性を持つ要素は、暗号化された nonce
がスクリプトにのみ公開されるようにし(CSS 属性セレクタなどのサイドチャネルには公開されません)、コンテンツ属性から値を取得し、[[CryptographicNonce]] という内部スロットに移動させ、スクリプトに HTMLOrSVGElement
インターフェースミックスインを介して公開し、コンテンツ属性を空文字列に設定します。特に指定がない限り、スロットの値は空文字列です。
element.nonce
element の暗号化された nonce に設定された値を返します。セッターが使用されていない場合、これは元々 nonce コンテンツ属性に見つかった値になります。
element.nonce = value
element の暗号化された nonce の値を更新します。
nonce
IDL 属性は、取得時にこの要素の [[CryptographicNonce]]
の値を返し、設定時にこの要素の [[CryptographicNonce]]
に設定された値を設定します。
nonce IDL
属性のセッターが対応するコンテンツ属性を更新しないことに注目してください。これと、ブラウジングコンテキストに接続されたときに要素の nonce
コンテンツ属性を空文字列に設定する以下の設定は、セレクタなどのコンテンツ属性を簡単に読み取れるメカニズムを介して nonce 値が外部に流出するのを防ぐために設けられています。この動作について詳しくは、issue #2369 で紹介されています。
次の 属性変更手順 は、nonce コンテンツ属性に使用されます:
element が 含む HTMLOrSVGElement
を持たない場合、リターンします。
localName が nonce
ではないか、または namespace が null でない場合、リターンします。
value が null の場合、element の [[CryptographicNonce]] を空文字列に設定します。
それ以外の場合、element の [[CryptographicNonce]] を value に設定します。
要素が 含む
HTMLOrSVGElement を ブラウジングコンテキストに接続されたとき、ユーザーエージェントはelementに対して次の手順を実行する必要があります:
CSP リストをelementのシャドウを含むルートのポリシーコンテナのCSP リストにします。
もしCSP リストがヘッダーによって提供された Content Security
Policy を含んでいる場合、elementが空文字列ではないnonceコンテンツ属性attrを持っている場合は:
nonce を element の[[CryptographicNonce]]に設定します。
element の [[CryptographicNonce]] を nonce に設定します。
もしelementの[[CryptographicNonce]] が復元されなければ、この時点で空文字列になります。
クローン手順
の要素について
含む
HTMLOrSVGElement
には、スロットの値を、クローンされる要素のスロットの値に設定する必要があります。
すべての最新エンジンでサポートされています。
レイジーローディング属性は、以下のキーワードと状態を持つ列挙属性です:
| キーワード | 状態 | 簡潔な説明 |
|---|---|---|
lazy
| Lazy | 条件が満たされるまでリソースのフェッチを遅らせるために使用されます。 |
eager
| Eager | リソースを即座にフェッチするために使用されます。デフォルトの状態です。 |
この属性は、ユーザーエージェントに対し、リソースを即座にフェッチするか、要素に関連する条件が満たされるまでフェッチを遅らせるよう指示します。
この属性の欠落値のデフォルトと無効値のデフォルトは、どちらもEager状態です。
レイジーロード要素のステップは、element に対して次のように行われます:
スクリプトが無効になっている場合 elementに対し、false を返します。
これは追跡防止策であり、スクリプトが無効になっているときにレイジーローディングがサポートされていると、ページのマークアップに画像を戦略的に配置することで、ユーザーの大まかなスクロール位置を追跡することが可能になってしまうためです。
element の レイジーローディング属性がLazy 状態にある場合、true を返します。
false を返します。
各imgおよびiframe要素には、関連するレイジーロード再開ステップがあり、最初は null に設定されています。
imgおよびiframe要素がレイジーロードを行う場合、これらのステップはレイジーロードインターセクションオブザーバーのコールバックから、またはレイジーローディング属性がEager状態に設定されたときに実行されます。これにより、要素のロードが続行されます。
各Documentには、最初は null に設定されているレイジーロードインターセクションオブザーバーがあり、IntersectionObserverインスタンスに設定できます。
レイジーローディング要素のインターセクション観察を開始するためにelementに対して、次の手順を実行します:
elementのノードドキュメントをdocとします。
もしdocのレイジーロードインターセクションオブザーバーが null
である場合、新しいIntersectionObserverインスタンスに設定します。初期設定は次のとおりです:
元のIntersectionObserverコンストラクタの値を使用することが意図されています。ただし、Intersection
Observerが仕様内での使用に適した低レベルのフックを公開するまでは、JavaScript で公開されたコンストラクタを使用する必要があります。これを追跡しているバグはw3c/IntersectionObserver#464を参照してください。[INTERSECTIONOBSERVER]
callbackはentriesとobserverという引数を使ってこれらのステップを実行します:
entries内の各entryに対して開発者が修正可能な配列アクセサやイテレーションフックをトリガーしない反復メソッドを使用して:
resumptionStepsを null に設定します。
もしentry.isIntersectingが
true の場合、resumptionStepsをentry.targetのレイジーロード再開ステップに設定します。
もしresumptionStepsが null の場合、リターンします。
レイジーローディング要素のインターセクション観察を停止するために、entry.targetに対して実行します。
entry.targetのレイジーロード再開ステップを
null に設定します。
resumptionStepsを呼び出します。
元のisIntersectingおよびtargetゲッターの値を使用することが意図されています。w3c/IntersectionObserver#464を参照してください。[INTERSECTIONOBSERVER]
optionsは、IntersectionObserverInit辞書であり、次の辞書メンバーを持ちます:
«[ "scrollMargin" → レイジーロードスクロールマージン ]»
これは、画像がまだビューポートと交差していないが、交差しそうなときにスクロール中に画像をフェッチすることを可能にします。
レイジーロードスクロールマージンの提案は値の動的な変更を意味していますが、IntersectionObserverAPIはスクロールマージンの変更をサポートしていません。問題についてはw3c/IntersectionObserver#428を参照してください。
docのレイジーロードインターセクションオブザーバーのobserveメソッドを呼び出し、引数にelementを設定します。
元のobserveメソッドの値を使用することが意図されています。w3c/IntersectionObserver#464を参照してください。[INTERSECTIONOBSERVER]
レイジーローディング要素のインターセクション観察を停止するためにelementに対して、次の手順を実行します:
elementのノードドキュメントをdocとします。
断言: docのレイジーロードインターセクションオブザーバーが null でないこと。
docのレイジーロードインターセクションオブザーバーのunobserveメソッドを呼び出し、引数にelementを設定します。
元のunobserveメソッドの値を使用することが意図されています。w3c/IntersectionObserver#464を参照してください。[INTERSECTIONOBSERVER]
レイジーロードスクロールマージンは実装依存の値ですが、以下の提案を考慮する必要があります:
リソースがビューポートに交差する前に、通常の使用パターン下で最も頻繁にリソースが読み込まれる最小値を設定します。
典型的なスクロール速度: スクロール速度が速いデバイスには値を増加させます。
現在のスクロール速度やモメンタム: ユーザーエージェントはスクロールがどこで止まる可能性が高いかを予測し、値を調整できます。
ネットワークの品質: 速度が遅いか、遅延が高い接続では値を増加させます。
ユーザーの好みにより値が影響されることがあります。
プライバシーのために、レイジーロードスクロールマージンが追加情報を漏洩しないことが重要です。例えば、現在のデバイスでの典型的なスクロール速度が不正確であっても、新しいフィンガープリントベクトルが導入されないようにする必要があります。
ブロッキング属性は、特定の操作が外部リソースのフェッチにおいてブロックされるべきであることを明示的に示します。ブロックされる可能性のある操作は、以下の表に示されている文字列であるブロッキングトークン候補によって表されます。
| ブロッキングトークン候補 | 説明 |
|---|---|
"render"
| この要素は潜在的にレンダーブロッキングである可能性があります。 |
将来的には、ブロッキングトークン候補が増える可能性があります。
ブロッキング属性には、スペースで区切られた順不同の一意のトークン集合であり、各トークンがブロッキングトークン候補である値を持たなければなりません。サポートされているトークンは、ブロッキング属性のブロッキングトークン候補です。任意の要素は、ブロッキング属性を最大で1つしか持つことができません。
要素elに対するブロッキングトークンセットは、以下の手順に従った結果です:
elのブロッキング属性の値をvalueとします。この属性が存在しない場合は空文字列とします。
valueをASCII小文字に変換されたvalueに設定します。
ASCII空白文字でvalueを分割した結果をrawTokensとします。
rawTokensの要素で、ブロッキングトークン候補であるものを含むセットを返します。
要素は、ブロッキングトークンセットに"render"が含まれている場合、または個々の要素で定義される暗黙的に潜在的にレンダーブロッキングである場合に、潜在的にレンダーブロッキングとなります。デフォルトでは、要素は暗黙的に潜在的にレンダーブロッキングではありません。
フェッチ優先属性は、次のキーワードと状態を持つ列挙属性です:
| キーワード | 状態 | 簡潔な説明 |
|---|---|---|
high
| high | 同じデスティネーションを持つ他のリソースに対して、フェッチが高優先度であることを示します。 |
low
| low | 同じデスティネーションを持つ他のリソースに対して、フェッチが低優先度であることを示します。 |
auto
| auto | 同じデスティネーションを持つ他のリソースに対して、フェッチの優先度を自動的に決定することを示します。 |
この属性の欠落値のデフォルトおよび無効値のデフォルトは、どちらもauto状態です。
反映のための構成要素は次のとおりです:
反映されたターゲットとは、要素またはElementInternals
オブジェクトです。これは通常、コンテキストから明確であり、反映されたIDL属性のインターフェイスと同一です。ElementInternals
オブジェクトの場合、それは常にそのインターフェイスと同一です。
反映されたIDL属性は、属性インターフェイスメンバーです。
反映されたコンテンツ属性名は文字列です。反映されたターゲットが要素である場合、それは名前空間がnullのコンテンツ属性のローカル名を表します。反映されたターゲットがElementInternals
オブジェクトである場合、それは反映されたターゲットのターゲット要素の内部コンテンツ属性マップのキーを表します。
反映されたIDL属性は、反映されるように定義できます。反映されたコンテンツ属性名が反映されたターゲットの。一般的には、IDL属性ゲッターがコンテンツ属性の現在の値を返し、セッターがコンテンツ属性の値を指定された値に変更することを意味します。
反映されたターゲットが要素である場合、反映されたIDL属性は、support
ElementInternalsを宣言することもできます。これにより、ElementInternalsインターフェイスも、同じ識別子で反映されたIDL属性を持ち、反映されたIDL属性が同じ反映されたコンテンツ属性名を反映することを意味します。
fooBarIDL属性は、foobarコンテンツ属性を反映し、support
ElementInternalsする必要があります。
反映されたターゲットには、次の関連アルゴリズムがあります:
反映されたターゲットが要素elementである場合、これらは次のように定義されます:
elementを返します。
attributeを、null、反映されたコンテンツ属性名、およびelementを指定して、名前空間とローカル名で属性を取得するの実行結果とします。
attributeがnullの場合、nullを返します。
attributeのvalueを返します。
属性値を設定するをelement、反映されたコンテンツ属性名、 およびvalueを指定して実行します。
名前空間とローカル名で属性を削除するを、null、反映されたコンテンツ属性名、 およびelementを指定して実行します。
反映されたターゲットがElementInternalsオブジェクトelementInternalsである場合、それらは次のように定義されます:
elementInternalsのターゲット要素を返します。
もしelementInternalsのターゲット要素の内部コンテンツ属性マップ[反映されたコンテンツ属性名]が存在しない場合、nullを返します。
elementInternalsのターゲット要素の内部コンテンツ属性マップ[反映されたコンテンツ属性名]を返します。
設定elementInternalsのターゲット要素の内部コンテンツ属性マップ[反映されたコンテンツ属性名]をvalueに。
削除elementInternalsのターゲット要素の内部コンテンツ属性マップ[反映されたコンテンツ属性名]を削除します。
これは、ElementInternalsオブジェクトの冗長なデータ構造につながります。これらのオブジェクトは、ターゲット要素の内部コンテンツ属性マップを直接操作することができず、反映が単方向にしか行われないためです。しかし、このアプローチは、反映されたターゲット間で共有されるIDL属性を定義し、共通のAPIセマンティクスの利点を享受するために、エラーを防ぐために選ばれました。
型がDOMStringまたはDOMString?のIDL属性は、反映されるコンテンツ属性が列挙された場合にのみ、既知の値のみに制限されることがあります。以下の処理モデルによると、そのようなIDL属性のゲッターは、その列挙された属性のキーワード、または空文字列またはnullのみを返します。
反映されたIDL属性が型DOMStringを持つ場合:
ゲッターステップは次のとおりです:
thisのget the elementを実行して、elementを取得します。
thisのget the content attributeを実行して、contentAttributeValueを取得します。
elementのコンテンツ属性定義を取得し、その名前空間がnullでローカル名が反映されたコンテンツ属性名に一致するものをattributeDefinitionとします。
もしattributeDefinitionが列挙された属性であり、反映されたIDL属性が既知の値のみに制限されるように定義されている場合:
contentAttributeValueがnullの場合、空文字列を返します。
contentAttributeValueを返します。
セッターステップは、thisのset the content attributeを指定された値で実行することです。
反映されたIDL属性が型DOMString?を持つ場合:
ゲッターステップは次のとおりです:
thisのget the elementを実行して、elementを取得します。
thisのget the content attributeを実行して、contentAttributeValueを取得します。
elementのコンテンツ属性定義を取得し、その名前空間がnullでローカル名が反映されたコンテンツ属性名に一致するものをattributeDefinitionとします。
確認: 反映されたIDL属性が既知の値のみに制限されていることを確認します。
確認: contentAttributeValueがattributeDefinitionの状態に対応していることを確認します。
contentAttributeValueがattributeDefinitionの状態に対応しており、関連するキーワード値がない場合、nullを返します。
attributeDefinitionの状態に対応するcontentAttributeValueの正準キーワードを返します。
セッターステップは次のとおりです:
指定された値がnullの場合、thisのdelete the content attributeを実行します。
それ以外の場合、thisのset the content attributeを指定された値で実行します。
反映されたIDL属性が型USVStringを持つ場合:
ゲッターステップは次のとおりです:
thisのget the elementを実行して、elementを取得します。
thisのget the content attributeを実行して、contentAttributeValueを取得します。
elementのコンテンツ属性定義を取得し、その名前空間がnullでローカル名が反映されたコンテンツ属性名に一致するものをattributeDefinitionとします。
もしattributeDefinitionがURLを含む場合:
contentAttributeValueがnullであれば、空文字列を返します。
urlStringを、URLのエンコーディング、パース、シリアライズを実行し、contentAttributeValueとelementのノードドキュメントに相対するようにして取得した結果とします。
urlStringが失敗でない場合、urlStringを返します。
contentAttributeValueを、スカラ値文字列に変換して返します。
セッターステップは、thisのset the content attributeを指定された値で実行することです。
反映されたIDL属性が型booleanを持つ場合:
ゲッターステップは次のとおりです:
thisのget the content attributeを実行して、contentAttributeValueを取得します。
contentAttributeValueがnullであれば、falseを返します。
trueを返します。
セッターステップは次のとおりです:
指定された値がfalseであれば、thisのdelete the content attributeを実行します。
指定された値がtrueであれば、thisのset the content attributeを空文字列で実行します。
これはbooleanコンテンツ属性のルールに対応します。
反映されたIDL属性が型long、またはオプションで非負数のみに制限されるとオプションでデフォルト値defaultValueを持つ場合:
ゲッターステップは次のとおりです:
thisのget the content attributeを実行して、contentAttributeValueを取得します。
もしcontentAttributeValueがnullでない場合:
整数パーシングを実行して、contentAttributeValueを取得します。もし反映されたIDL属性が非負数のみに制限されない場合; それ以外の場合は非負整数パーシングを実行して取得します。
もしparsedValueがエラーでなく、かつlong範囲内であれば、parsedValueを返します。
もし反映されたIDL属性がデフォルト値を持つ場合、defaultValueを返します。
もし反映されたIDL属性が非負数のみに制限される場合、-1を返します。
0を返します。
セッターステップは次のとおりです:
もし反映されたIDL属性が非負数のみに制限されるかつ指定された値が負の場合、"IndexSizeError"DOMExceptionをスローします。
minimumを0に設定します。
もし反映されたIDL属性が正の数にのみ制限されるまたはフォールバック付きで正の数にのみ制限される場合、minimumを1に設定します。
newValueをminimumに設定します。
もし反映されたIDL属性がデフォルト値を持つ場合、newValueをdefaultValueに設定します。
もし指定された値がminimumから2147483647の範囲内である場合、それをnewValueに設定します。
thisのset the content attributeを実行して、newValueを最短の文字列に変換し、有効な整数として表現します。
範囲に制限はセッターステップには影響を与えません。
反映されたIDL属性が型double、オプションで正の数にのみ制限されるとオプションでデフォルト値defaultValueを持つ場合:
ゲッターステップは次のとおりです:
thisのget the content attributeを実行して、contentAttributeValueを取得します。
もしcontentAttributeValueがnullでない場合:
浮動小数点数値のパースを実行して、contentAttributeValueを取得します。
もしparsedValueがエラーでなく、かつ0より大きい場合、parsedValueを返します。
もしparsedValueがエラーでなく、反映されたIDL属性が正の数にのみ制限されない場合、parsedValueを返します。
もし反映されたIDL属性がデフォルト値を持つ場合、defaultValueを返します。
0を返します。
セッターステップは次のとおりです:
もし反映されたIDL属性が正の数にのみ制限されかつ指定された値が0より大きくない場合、returnします。
thisのset the content attributeを指定された値で実行し、その値を浮動小数点数としての最適な表現に変換します。
InfinityとNot-a-Number (NaN)の値は、Web IDLで定義されているように、設定時に例外をスローします。[WEBIDL]
反映されたIDL属性が型DOMTokenListを持つ場合、そのゲッターステップは、関連する要素がthisであり、関連する属性のローカル名が反映されたコンテンツ属性名であるDOMTokenListオブジェクトを返すことです。仕様著者は、この型のIDL属性に対してsupport
ElementInternalsを使用することはできません。
反映されたIDL属性が型T?を持ち、TがElementまたはElementから継承するインターフェイスである場合、attrが反映されたコンテンツ属性名の場合:
その反映されたターゲットは、明示的に設定された attr-要素を持ちます。これは要素への弱い参照またはnullです。最初はnullです。
その反映されたターゲットであるreflectedTargetは、次のステップを実行するattr-関連要素を取得するアルゴリズムを持ちます:
reflectedTargetのget the elementを実行して、elementを取得します。
reflectedTargetのget the content attributeを実行して、contentAttributeValueを取得します。
もしreflectedTargetの明示的に設定されたattr-要素がnullでない場合:
もしreflectedTargetの明示的に設定されたattr-要素が、elementの任意の子孫であり、elementの任意の影響を受ける先祖のいずれかの影響を受ける先祖である場合、それを返します。
nullを返します。
それ以外の場合、もしcontentAttributeValueがnullでない場合、次の条件を満たす最初の要素candidateをツリー順で返します:
そのような要素が存在しない場合、nullを返します。
nullを返します。
ゲッターステップは、thisのget the attr-associated elementの実行結果を返すことです。
セッターステップは次のとおりです:
指定された値がnullの場合:
thisのexplicitly set attr-elementをnullに設定します。
thisのdelete the content attributeを実行します。
returnします。
thisのset the content attributeを空文字列で実行します。
thisのexplicitly set attr-elementを指定された値の弱い参照に設定します。
要素反映されたターゲットのみ: 以下の属性変更ステップは、element、localName、oldValue、value、およびnamespaceを指定して、コンテンツ属性とIDL属性の間の同期を行うために使用されます:
もしlocalNameがattrでないか、namespaceがnullでない場合、returnします。
elementのexplicitly set attr-elementをnullに設定します。
この型の反映されたIDL属性は、一貫性を保つために識別子を"Element"で終わらせることが強く推奨されます。
もし反映されたIDL属性
がFrozenArray<T>?型を持つ場合、ここでTはElement
またはElementから継承されるインターフェースのいずれかであるとします。
次に、
attrが反映されたコンテンツ属性名
である場合は次のようになります:
その反映ターゲット には明示的に設定されたattr-要素があり、それはリストまたはnullへの弱参照のいずれかです。初期値はnullです。
その反映ターゲット にはキャッシュされたattr-関連要素があり、それはリストの要素です。初期値は« »です。
その反映ターゲット
にはキャッシュされたattr-関連要素オブジェクトがあり、それはFrozenArray<T>?です。初期値はnullです。
その反映ターゲット reflectedTargetには、次の手順を実行するattr-関連要素を取得するアルゴリズムがあります:
elementsを空のリストにします。
elementをreflectedTargetの要素を取得するの結果にします。
もしreflectedTargetの明示的に設定されたattr-要素がnullでない場合:
各 attrElementをreflectedTargetの明示的に設定されたattr-要素である場合:
もしattrElementがelementの任意の子孫でなく、かつ影響を受ける先祖のいずれかの影響を受ける先祖でない場合、続行します。
attrElementを elementsに追加します。
それ以外の場合:
contentAttributeValueをreflectedTargetのコンテンツ属性を取得する実行結果にします。
もしcontentAttributeValueがnullの場合はnullを返します。
tokensをcontentAttributeValue、ASCIIの空白で分割します。
各 idをtokensである場合:
elementsを返します。
ゲッターステップは次のとおりです:
elementsをthisのattr-関連要素を取得する実行結果にします。
もしelementsの内容がthisのキャッシュされたattr-関連要素の内容と等しい場合は、thisのキャッシュされたattr-関連要素オブジェクトを返します。
elementsAsFrozenArrayをelements、に変換された
FrozenArray<T>?にします。
thisのキャッシュされたattr-関連要素をelementsに設定します。
thisのキャッシュされたattr-関連要素オブジェクトをelementsAsFrozenArrayに設定します。
elementsAsFrozenArrayを返します。
この追加のキャッシュレイヤーは、element.reflectedElements === element.reflectedElementsという不変条件を維持するために必要です。
セッターステップは次のとおりです:
指定された値がnullの場合:
thisの明示的に設定されたattr-要素をnullに設定します。
thisのコンテンツ属性を削除するを実行します。
終了します。
thisのコンテンツ属性を設定するを空の文字列で実行します。
elementsを空のリストにします。
各 elementを指定された値である場合:
elementの弱参照を elementsに追加します。
thisの明示的に設定されたattr-要素をelementsに設定します。
要素反映ターゲットのみの場合: 次の属性変更ステップが、element、localName、oldValue、value、およびnamespaceを使用してコンテンツ属性とIDL属性を同期させるために使用されます:
もしlocalNameがattrでないか、またはnamespaceがnullでない場合は、終了します。
elementの明示的に設定されたattr-要素をnullに設定します。
このタイプの反映されたIDL属性には、一貫性を保つために識別子の末尾に「Elements」を付けることが強く推奨されます。
リフレクションは主に、反映されたIDL属性を通じてコンテンツ属性への型付きアクセスを提供することで、ウェブ開発者の利便性を向上させることを目的としています。ウェブプラットフォームが基づいている最終的な信頼性の源は、コンテンツ属性そのものです。つまり、仕様の著者は、反映されたIDL属性のゲッターやセッターのステップを使用するのではなく、コンテンツ属性の存在と値を使用しなければなりません。(または、列挙された属性の状態など、上にある抽象化されたものを使用します。)
このルールには、次のような型を持つ反映されたIDL属性に関して重要な例外が2つあります:
これらの場合、仕様の著者は反映ターゲットのattr-関連要素を取得するおよびattr-関連要素を取得するをそれぞれ使用しなければなりません。コンテンツ属性の存在と値は使用してはならず、それらは反映されたIDL属性と完全には同期できません。
反映ターゲットの明示的に設定されたattr-要素、明示的に設定されたattr-要素、キャッシュされたattr-関連要素、およびキャッシュされたattr-関連要素オブジェクトは内部実装の詳細として扱われ、使用されるべきではありません。
HTMLFormControlsCollection
およびHTMLOptionsCollection
インターフェースは、コレクションであり、HTMLCollection
インターフェースから派生しています。HTMLAllCollection
インターフェースはコレクションですが、派生はしていません。
HTMLAllCollection
インターフェースHTMLAllCollection
インターフェースは、レガシー属性であるdocument.all
のために使用されます。これはHTMLCollectionと同様に機能しますが、主な違いは、そのメソッドのさまざまな(誤用も含む)使用法が全て何かしらの結果を返すことと、プロパティアクセスの代わりに関数として呼び出すことができることです。
すべてのHTMLAllCollection
オブジェクトはDocumentにルートを持ち、すべての要素に一致するフィルタを持つため、コレクションによって表されるHTMLAllCollection
オブジェクトの要素は、ルートDocumentのすべての子孫要素で構成されています。
HTMLAllCollectionインターフェイスを実装するオブジェクトは、レガシープラットフォームオブジェクトであり、以下のセクションに記載されている追加の[[Call]]内部メソッドを持ちます。また、[[IsHTMLDDA]]内部スロットも持っています。
HTMLAllCollection
インターフェースを実装するオブジェクトは、[[IsHTMLDDA]]内部スロットを持つため、いくつかの異常な動作をします:
JavaScriptのToBoolean抽象操作は、HTMLAllCollection
インターフェースを実装するオブジェクトを与えられたときにfalseを返します。
IsLooselyEqual抽象操作は、HTMLAllCollection
インターフェースを実装するオブジェクトが与えられたとき、undefinedおよびnull値と比較するときにtrueを返します。
(IsStrictlyEqual抽象操作を使用した比較や、他の値(文字列やオブジェクトなど)に対するIsLooselyEqualの比較には影響しません。)
JavaScriptでtypeof
演算子がHTMLAllCollection
インターフェースを実装するオブジェクトに適用された場合、文字列"undefined"を返します。
これらの特別な動作は、2つの種類のレガシーコンテンツとの互換性を目的としています: 1つは、document.all
の存在を使用してレガシーユーザーエージェントを検出するもの、もう1つは、そのレガシーユーザーエージェントのみをサポートし、document.all
オブジェクトをその存在をテストせずに使用するものです。
[JAVASCRIPT]
[Exposed =Window ,
LegacyUnenumerableNamedProperties ]
interface HTMLAllCollection {
readonly attribute unsigned long length ;
getter Element (unsigned long index );
getter (HTMLCollection or Element )? namedItem (DOMString name );
(HTMLCollection or Element )? item (optional DOMString nameOrIndex );
// Note: HTMLAllCollection objects have a custom [[Call]] internal method and an [[IsHTMLDDA]] internal slot.
};
オブジェクトのサポートされているプロパティインデックスは、HTMLCollection
オブジェクトに定義されているものと同じです。
サポートされているプロパティ名には、すべての要素のid属性の非空の値、およびすべてのコレクションによって表されるname属性の非空の値が含まれます。これらは"all"-named要素に含まれるものであり、ツリー順に従い、後続の重複を無視し、要素が両方を提供する場合、idがnameよりも優先されます。
lengthゲッターステップは、コレクションによって表されるノードの数を返すことです。
インデックス付きプロパティゲッターは、渡されたインデックスを考慮して、"all"-indexed要素を取得する結果を返す必要があります。
namedItem(name)メソッドステップは、渡されたnameを考慮して、"all"-named要素を取得する結果を返すことです。
item(nameOrIndex)メソッドステップは次のとおりです:
nameOrIndexが提供されていない場合は、nullを返します。
渡されたnameOrIndexを考慮して、"all"-indexedまたはnamed要素を取得する結果を返します。
以下の要素は"all"-named要素です:
a,
button,
embed,
form,
frame,
frameset,
iframe,
img,
input,
map,
meta,
object,
select,
および
textarea
"all"-indexed要素を取得するために、
HTMLAllCollection
collectionからインデックスindexを与えられた場合、collection内のindex番目の要素を返すか、そのようなindex番目の要素が存在しない場合はnullを返します。
"all"-named要素を取得するために、
HTMLAllCollection
collectionからnameを与えられた場合、次の手順を実行します:
nameが空文字列の場合、nullを返します。
subCollectionを、同じDocumentにルートを持つHTMLCollection
オブジェクトとし、そのフィルタが次のいずれかにのみ一致するものとします:
"all"-named要素のname属性がnameと等しいもの、または、
ID がnameと等しいもの。
subCollectionに正確に1つの要素が含まれている場合、その要素を返します。
それ以外の場合、subCollectionが空である場合はnullを返します。
それ以外の場合、subCollectionを返します。
"all"-indexedまたはnamed要素を取得するために、
HTMLAllCollection
collectionからnameOrIndexを与えられた場合、次の手順を実行します:
JavaScriptの文字列値に変換されたnameOrIndexが配列インデックスプロパティ名である場合、渡されたnameOrIndexによって表される数値を考慮して、"all"-indexed要素を取得する結果を返します。
渡されたnameOrIndexを考慮して、"all"-named要素を取得する結果を返します。
もしargumentsListのサイズがゼロであるか、argumentsList[0]がundefinedである場合、nullを返します。
resultを、"all"-インデックスまたは名前付き要素を取得する
このHTMLAllCollectionから
nameOrIndexを与えられたものとします。
resultをECMAScript値に変換する結果を返します。
thisArgumentは無視されるため、Function.prototype.call.call(document.all, null, "x")のようなコードでも要素の検索を行います。(document.all.callは存在しません。なぜならdocument.allはFunction.prototypeを継承していないためです。)
HTMLFormControlsCollection
インターフェースHTMLFormControlsCollection
インターフェースは、form要素内のコレクションとして、リストされた要素に使用されます。
現在のすべてのエンジンでサポートされています。
現在のすべてのエンジンでサポートされています。
[Exposed =Window ]
interface HTMLFormControlsCollection : HTMLCollection {
// inherits length and item()
getter (RadioNodeList or Element )? namedItem (DOMString name ); // shadows inherited namedItem()
};
[Exposed =Window ]
interface RadioNodeList : NodeList {
attribute DOMString value ;
};
collection.length
collection内の要素の数を返します。
element = collection.item(index)
element = collection[index]
collection内のインデックスindexにある項目を返します。項目はツリー順に並べ替えられます。
element = collection.namedItem(name)
HTMLFormControlsCollection/namedItem
現在のすべてのエンジンでサポートされています。
radioNodeList = collection.namedItem(name)
element = collection[name]
radioNodeList = collection[name]
collectionからIDまたは
name
nameを持つ項目を返します。
一致する項目が複数ある場合、それらすべての要素を含むRadioNodeList
オブジェクトが返されます。
radioNodeList.value
radioNodeListによって表される最初のチェックされたラジオボタンの値を返します。
radioNodeList.value = value
radioNodeListによって表される最初のラジオボタンで、値がvalueに等しいものをチェックします。
オブジェクトのサポートされているプロパティインデックスは、HTMLCollection
オブジェクトに定義されているものと同じです。
サポートされているプロパティ名には、すべての要素のid属性の非空の値、およびすべてのコレクションによって表されるname属性の非空の値が含まれます。これらは"all"-named要素に含まれるものであり、ツリー順に従い、後続の重複を無視し、要素が両方を提供する場合、idがnameよりも優先されます。
namedItem(name)メソッドは、次のアルゴリズムに従って動作する必要があります:
id属性またはname属性を持つノードがコレクション内に1つだけある場合、そのノードを返してアルゴリズムを終了します。
id属性またはname属性を持つノードがコレクション内に存在しない場合、nullを返してアルゴリズムを終了します。
RadioNodeListオブジェクトを作成し、それはHTMLFormControlsCollectionオブジェクトのライブビューを表し、さらにフィルタリングしてnameに等しいid属性またはname属性を持つノードのみが含まれるようにします。RadioNodeListオブジェクト内のノードはツリー順に並べ替えられる必要があります。
RadioNodeListオブジェクトを返します。
RadioNodeListインターフェースのメンバーは、NodeListオブジェクトでの動作と同じように振る舞う必要があります。
現在のすべてのエンジンでサポートされています。
value
IDL属性は、RadioNodeListオブジェクト上で、取得時には次の手順を実行した結果の値を返す必要があります。
elementを、ツリー順で最初にRadioNodeListオブジェクトによって表される、input要素で、そのtype属性がRadio
Button状態であり、チェックされているのがtrueであるものとします。そうでない場合はnullとします。
elementがnullである場合、空文字列を返します。
elementがvalue属性を持たない要素である場合、文字列「on」を返します。
それ以外の場合は、elementのvalue属性の値を返します。
設定時には、valueIDL属性は次の手順を実行する必要があります。
新しい値が文字列「on」である場合、elementを、次の手順に従ってRadioNodeListオブジェクトによって表される最初の要素とします。ツリー順で、input要素であり、そのtype属性がRadio
Button状態であり、そのvalueコンテンツ属性が存在しないか、存在し、新しい値と等しい場合とします。そのような要素が存在しない場合は、代わりにelementをnullとします。
それ以外の場合、elementを、ツリー順で最初の要素とします。RadioNodeListオブジェクトによって表される、input要素で、そのtype属性がRadio
Button状態であり、そのvalueコンテンツ属性が存在し、新しい値と等しい場合とします。そのような要素が存在しない場合は、代わりにelementをnullとします。
もしelementがnullでない場合、そのチェックされている状態をtrueに設定します。
HTMLOptionsCollection
インターフェースすべてのエンジンでサポートされています。
HTMLOptionsCollection
インターフェースは、option 要素の
コレクション
に使用されます。常に select
要素にルートされており、その要素の子孫を操作するための属性やメソッドを持っています。
[Exposed =Window ]
interface HTMLOptionsCollection : HTMLCollection {
// inherits item(), namedItem()
[CEReactions ] attribute unsigned long length ; // shadows inherited length
[CEReactions ] setter undefined (unsigned long index , HTMLOptionElement ? option );
[CEReactions ] undefined add ((HTMLOptionElement or HTMLOptGroupElement ) element , optional (HTMLElement or long )? before = null );
[CEReactions ] undefined remove (long index );
attribute long selectedIndex ;
};
collection.length
collection の要素数を返します。
collection.length = value
既存の長さよりも小さい値を設定すると、collection に対応するコンテナ内の option
要素の数が切り詰められます。
既存の長さよりも大きい値を設定すると、その値が100000以下である限り、collection に対応するコンテナに新しい空白の option
要素が追加されます。
element = collection.item(index)
element = collection[index]
collection 内のインデックス index にある項目を返します。アイテムはツリー順でソートされています。
collection[index] = element
index が collection 内のアイテム数よりも大きい場合、対応するコンテナに新しい空白の option
要素を追加します。
null に設定すると、collection からインデックス index の項目を削除します。
オプション要素が設定されている場合、collection 内のインデックス index にその要素を追加または置き換えます。
element = collection.namedItem(name)
element = collection[name]
collection から、ID または name が
name に一致するアイテムを返します。
複数の一致するアイテムがある場合、最初のものが返されます。
collection.add(element[, before])
element を before で指定されたノードの前に挿入します。
before 引数は数値でもかまいません。その場合、element はその番号のアイテムの前に挿入されます。collection の要素である場合、その要素の前に element を挿入します。
before が省略された場合、null または範囲外の数値の場合、element はリストの最後に追加されます。
element が挿入される要素の祖先である場合、"HierarchyRequestError" DOMException
がスローされます。
collection.remove(index)
collection からインデックス index の項目を削除します。
collection.selectedIndex
最初の選択項目のインデックスを返します。選択項目がない場合は -1 を返します。
collection.selectedIndex = index
collection 内のインデックス index の option
要素に選択を変更します。
対応するプロパティ インデックスは、HTMLCollection
オブジェクトで定義されています。
length のゲッターは、コレクションが表すノードの数を返します。
length
のセッターは次の手順に従います。
現在のノードの数を represented by the collection として取得します。
指定された値が current より大きい場合、次の操作を行います。
指定された値が 100,000 を超える場合、何も返さないで終了します。
n を value - current として取得します。
新しい option
要素を、属性や子ノードなしで select
要素に追加します。this がルートになっている DocumentFragment
に含まれる新しい option
要素が挿入されたかのように、変更イベントが発生する必要があります。
指定された値が current より小さい場合、次の操作を行います。
n を current - value として取得します。
コレクションの最後の n ノードをその親ノードから削除します。
length
を設定しても、optgroup
要素が削除または追加されることはなく、既存の optgroup
要素に新しい子が追加されることもありません(ただし、既存の子が削除されることはあります)。
対応するプロパティ名には、コレクションが表すすべての要素の id および name
属性の空でない値が含まれます。これらは ツリー順
で並び替えられ、後の重複を無視します。要素が両方の値を持ち、それらが異なり、どちらも以前のエントリの重複でない場合、要素の id が name
よりも先に来ます。
ユーザー エージェントが 新しいインデックス付きプロパティの値を設定する または 既存のインデックス付きプロパティの値を設定する 際には、次のアルゴリズムを実行する必要があります。
value が null の場合、remove
メソッドの手順を index を引数として呼び出し、終了します。
length を コレクションが表すノード の数として取得します。
n を index - length として取得します。
n がゼロより大きい場合、新しい属性や子ノードのない option
要素が含まれる DocumentFragment
を select
要素に追加します。
n がゼロ以上の場合、value を select
要素に追加します。それ以外の場合、コレクション内の index 番目の要素を value に置き換えます。
add(element, before)
メソッドは、次のアルゴリズムに従って動作する必要があります。
element が select
要素の祖先である場合、HTMLOptionsCollection
にルートされている場合、"HierarchyRequestError" DOMException
をスローします。
before が要素であり、その要素が select
要素の子孫でない場合、HTMLOptionsCollection
にルートされている場合、"NotFoundError" DOMException
をスローします。
element と before が同じ要素である場合、何も返さず終了します。
before がノードである場合、そのノードを reference とします。そうでない場合、before が整数であり、コレクション内に before 番目のノードが存在する場合、そのノードを reference とします。それ以外の場合は、reference を null とします。
reference が null でない場合、reference の親ノードを parent
とします。それ以外の場合、parent を select
要素とします。HTMLOptionsCollection
にルートされている要素を親ノードとします。
Pre-insert element を parent ノードに reference の前に挿入します。
remove(index) メソッドは、次のアルゴリズムに従って動作する必要があります。
コレクションが表すノードの数がゼロの場合、何も返さず終了します。
index が 0 以上の数値でなく、かつコレクションが表すノードの数より小さい場合、何も返さず終了します。
element をコレクション内の index 番目の要素とします。
element をその親ノードから削除します。
selectedIndex IDL 属性は、select
要素の同名の属性と同様に動作する必要があります。HTMLOptionsCollection
にルートされています。
DOMStringList
インターフェースすべての現行エンジンでサポートされています。
DOMStringList
インターフェースは、文字列のリストを表す非モダンなレトロな方法です。
[Exposed =(Window ,Worker )]
interface DOMStringList {
readonly attribute unsigned long length ;
getter DOMString ? item (unsigned long index );
boolean contains (DOMString string );
};
新しいAPIはsequence<DOMString>または
これに相当するものを使用し、DOMStringListを使用してはなりません。
strings.length
stringsに含まれる文字列の数を返します。
strings[index]
strings.item(index)
stringsからインデックスindexにある文字列を返します。
strings.contains(string)
stringsにstringが含まれている場合はtrueを、それ以外の場合はfalseを返します。
各DOMStringList
オブジェクトには、リストが関連付けられています。
DOMStringList
インターフェースはインデックス付きプロパティをサポートします。
対応するプロパティ インデックスは、この
オブジェクトの関連リストのインデックスです。
すべての現行エンジンでサポートされています。
length
ゲッターの手順は、関連リストのこのオブジェクトのサイズを返すことです。
すべての現行エンジンでサポートされています。
item(index) メソッドの手順は、
index番目の項目をこのオブジェクトの関連リストから返すこと、indexプラス1が関連リストのサイズを超える場合はnullを返すことです。
すべての現行エンジンでサポートされています。
contains(string) メソッドの手順は、このオブジェクトの関連リストがstringを含んでいる場合はtrueを、それ以外の場合はfalseを返すことです。
JavaScriptオブジェクトを含む、
プラットフォームオブジェクト
を異なるレルム
の間で受け渡すことをサポートするために、この仕様はオブジェクトのシリアル化とデシリアル化のためのインフラストラクチャを定義しています。場合によってはデータのコピーではなく、基になるデータの転送が行われることもあります。このシリアル化/デシリアル化プロセスは「構造化複製」として総称されますが、ほとんどのAPIは別々のシリアル化とデシリアル化のステップを実行します。(例外として、structuredClone()
メソッドがあります。)
このセクションでは、JavaScript仕様の用語とタイポグラフィの慣例を使用します。[JAVASCRIPT]
/developer.mozilla.org/en-US/docs/Glossary/Serializable_object
/developer.mozilla.org/en-US/docs/Glossary/Serializable_object
/developer.mozilla.org/en-US/docs/Glossary/Serializable_object
/developer.mozilla.org/en-US/docs/Glossary/Serializable_object
シリアル化可能なオブジェクト はシリアル化され、後でデシリアル化されることができます。これは、特定の レルムに依存しません。これにより、ディスクに保存され 後で復元されたり、エージェント間や エージェントクラスタ を越えてクローンを作成することができます。
すべてのオブジェクトがシリアル化可能オブジェクト であるわけではなく、すべての シリアル化可能オブジェクト の側面が必ずしもシリアル化されるとは限りません。
プラットフォームオブジェクト
は、その主要インターフェースが
[Serializable]
IDL拡張属性で装飾されている場合、シリアル化可能なオブジェクトとなることができます。このようなインターフェースは、以下のアルゴリズムを定義する必要があります。
valueのデータをserializedのフィールドにシリアル化する手順です。serializedにシリアル化されたデータは、どの レルム にも依存しないものでなければなりません。
シリアル化が不可能な場合、これらの手順は例外をスローすることがあります。
これらの手順は、ネストされたデータ構造をシリアル化するために サブシリアル化 を実行することがあります。StructuredSerialize を直接呼び出すべきではありません。そうすると、重要なmemory引数が省略されるためです。
これらの手順の導入において、アルゴリズムに関連しない場合は forStorage引数に言及することを省略する必要があります。
serializedのデータをデシリアル化し、それを使用して valueを適切に設定する一連の手順です。valueは、内部データが設定されていない新しく作成された プラットフォームオブジェクトのインスタンスになります。 それを設定するのはこれらの手順の役割です。
デシリアル化が不可能な場合、これらの手順は例外をスローすることがあります。
これらの手順は、ネストされたデータ構造をデシリアル化するために サブデシリアル化 を実行することがあります。StructuredDeserialize を直接呼び出すべきではありません。そうすると、重要なtargetRealmおよびmemory引数が省略されるためです。
各プラットフォームオブジェクトの定義により、これらの手順でシリアル化およびデシリアル化されるデータが決定されます。通常、これらの手順は非常に対称的です。
[Serializable]拡張属性は、
引数を取るべきではなく、インターフェースにのみ表示される必要があります。また、インターフェースに複数回表示されるべきではありません。
特定のプラットフォームオブジェクトに対しては、
そのオブジェクトの主要なインターフェースのみが
(デ)シリアル化プロセス中に考慮されます。したがって、インターフェースの定義に継承が含まれる場合、
継承チェーン内の各[Serializable]
で注釈されたインターフェースは、独立したシリアル化手順
およびデシリアル化手順を定義し、
継承されたインターフェースから生じる可能性のある重要なデータを考慮に入れる必要があります。
たとえば、プラットフォームオブジェクトPersonを定義しているとし、
それに関連する2つのデータがあります:
名前の値で、これは文字列です。
親友の値で、これは他のPersonインスタンスかnullです。
その後、Personインスタンスをシリアル化可能オブジェクト
にすることができ、Personインターフェースに[Serializable]
拡張属性で注釈し、次の付随するアルゴリズムを定義することで実現できます:
serialized.[[Name]]にvalueの関連する名前の値を設定します。
serializedBestFriendを、valueの関連する親友の値の サブシリアル化に設定します。
serialized.[[BestFriend]]にserializedBestFriendを設定します。
valueの関連する名前の値をserialized.[[Name]]に設定します。
deserializedBestFriendを、serialized.[[BestFriend]]の サブデシリアル化に設定します。
valueの関連する親友の値をdeserializedBestFriendに設定します。
JavaScript仕様で定義されているオブジェクトは、 StructuredSerialize 抽象操作によって直接処理されます。
元々、この仕様では、あるレルムから別のレルムに複製できる「複製可能オブジェクト」の概念が定義されていました。しかし、より複雑な状況での動作を明確に指定するために、モデルが更新され、シリアル化とデシリアル化が明示的に行われるようになりました。
転送可能なオブジェクト は、エージェント間で転送されることをサポートします。転送は、基になるデータへの参照を共有しながらオブジェクトを再作成し、その後転送されるオブジェクトをデタッチすることを実質的に意味します。これは高価なリソースの所有権を移転するのに役立ちます。すべてのオブジェクトが転送可能なオブジェクトであるわけではなく、転送可能なオブジェクトであっても、そのすべての側面が転送時に必ずしも保存されるわけではありません。
転送は不可逆かつ冪等ではない操作です。いったんオブジェクトが転送されると、それは再び転送されたり、使用されたりすることはできません。
プラットフォームオブジェクトは、転送可能なオブジェクトになることができます。その主要インターフェースが、[Transferable]IDL拡張属性で装飾されている場合、そのようなインターフェースは以下のアルゴリズムも定義する必要があります。
valueのデータをdataHolderのフィールドに転送する一連の手順です。dataHolderに保持される結果のデータは、任意のレルムに依存しないものでなければなりません。
これらの手順は、転送が不可能な場合に例外をスローすることがあります。
dataHolderのデータを受信し、それを使用してvalueを適切に設定する一連の手順です。valueは、質問中のプラットフォームオブジェクト型の新しく作成されたインスタンスであり、内部データは設定されていません。これを設定するのがこれらの手順の役割です。
受信が不可能な場合、これらの手順は例外をスローすることがあります。
各プラットフォームオブジェクトの定義により、これらの手順でどのデータが転送されるかが決定されます。通常、これらの手順は非常に対称的です。
[Transferable]拡張属性は、
引数を取るべきではなく、インターフェースにのみ表示される必要があります。また、インターフェースに複数回表示されるべきではありません。
特定のプラットフォームオブジェクトに対しては、そのオブジェクトの主要インターフェースのみが転送プロセス中に考慮されます。したがって、インターフェースの定義に継承が含まれる場合、継承チェーン内の各[Transferable]で注釈されたインターフェースは、独立した転送手順および転送受信手順
を定義し、継承されたインターフェースから生じる可能性のある重要なデータを考慮に入れる必要があります。
プラットフォームオブジェクトで、転送可能なオブジェクトは、[[Detached]]内部スロットを持ちます。これにより、いったんプラットフォームオブジェクトが転送されると、それを再度転送することはできなくなります。
JavaScript仕様で定義されているオブジェクトは、StructuredSerializeWithTransfer抽象操作によって直接処理されます。
StructuredSerializeInternal抽象操作は、JavaScriptの値valueを入力として受け取り、それをレルムレルムに依存しない形にシリアル化し、ここではレコードとして表現されます。このシリアル化された形式には、後で異なるレルムで新しいJavaScriptの値にデシリアル化するために必要な情報がすべて含まれています。
このプロセスは、たとえばシリアル化できないオブジェクトをシリアル化しようとすると例外をスローすることがあります。
memoryが提供されていない場合、memoryを空のマップとします。
memoryマップの目的は、オブジェクトを2回シリアル化しないようにすることです。これにより、サイクルとグラフ内の重複するオブジェクトの同一性が保持されます。
memory[value]が存在する場合は、memory[value]を返します。
deepをfalseに設定します。
もしType(value)がUndefined, Null, Boolean, Number, BigInt, またはStringである場合、{ [[Type]]: "primitive", [[Value]]: value }を返します。
もしType(value)
がSymbolである場合、"DataCloneError" DOMExceptionをスローします。
serializedを未初期化の値に設定します。
もしvalueが[[BooleanData]]内部スロットを持っている場合、serializedを{ [[Type]]: "Boolean", [[BooleanData]]: value.[[BooleanData]] }に設定します。
それ以外の場合、valueが[[NumberData]]内部スロットを持っている場合、serializedを{ [[Type]]: "Number", [[NumberData]]: value.[[NumberData]] }に設定します。
それ以外の場合、valueが[[BigIntData]] 内部スロットを持っている場合、serializedを{ [[Type]]: "BigInt", [[BigIntData]]: value.[[BigIntData]] }に設定します。
それ以外の場合、valueが[[StringData]]内部スロットを持っている場合、serializedを{ [[Type]]: "String", [[StringData]]: value.[[StringData]] }に設定します。
それ以外の場合、valueが[[DateValue]]内部スロットを持っている場合、serializedを{ [[Type]]: "Date", [[DateValue]]: value.[[DateValue]] }に設定します。
それ以外の場合、valueが[[RegExpMatcher]]内部スロットを持っている場合、serializedを{ [[Type]]: "RegExp", [[RegExpMatcher]]: value.[[RegExpMatcher]], [[OriginalSource]]: value.[[OriginalSource]], [[OriginalFlags]]: value.[[OriginalFlags]] }に設定します。
それ以外の場合、valueが[[ArrayBufferData]]内部スロットを持っている場合:
もしIsSharedArrayBuffer(value)がtrueである場合:
もし現在の設定オブジェクトのクロスオリジン隔離能力がfalseである場合、"DataCloneError" DOMExceptionをスローします。
このチェックは、SharedArrayBufferがエージェントクラスターagent
clusterを離れることができないため、シリアル化時(デシリアル化時ではない)にのみ必要です。
もしforStorageがtrueである場合、"DataCloneError" DOMExceptionをスローします。
もしvalueが[[ArrayBufferMaxByteLength]]内部スロットを持っている場合、serializedを{ [[Type]]: "GrowableSharedArrayBuffer", [[ArrayBufferData]]: value.[[ArrayBufferData]], [[ArrayBufferByteLengthData]]: value.[[ArrayBufferByteLengthData]], [[ArrayBufferMaxByteLength]]: value.[[ArrayBufferMaxByteLength]], [[AgentCluster]]: 周囲のエージェントのエージェントクラスター }に設定します。
それ以外の場合、serializedを{ [[Type]]: "SharedArrayBuffer", [[ArrayBufferData]]: value.[[ArrayBufferData]], [[ArrayBufferByteLength]]: value.[[ArrayBufferByteLength]], [[AgentCluster]]: 周囲のエージェントのエージェントクラスター }に設定します。
それ以外の場合:
もしIsDetachedBuffer(value)がtrueである場合、"DataCloneError" DOMExceptionをスローします。
sizeをvalue.[[ArrayBufferByteLength]]に設定します。
dataCopyを?CreateByteDataBlock(size)に設定します。
これは、割り当てに失敗した場合にRangeError例外をスローする可能性があります。
実行するCopyDataBlockBytes(dataCopy, 0, value.[[ArrayBufferData]], 0, size)。
もしvalueが[[ArrayBufferMaxByteLength]]内部スロットを持っている場合、serializedを{ [[Type]]: "ResizableArrayBuffer", [[ArrayBufferData]]: dataCopy, [[ArrayBufferByteLength]]: size, [[ArrayBufferMaxByteLength]]: value.[[ArrayBufferMaxByteLength]] }に設定します。
それ以外の場合、serializedを{ [[Type]]: "ArrayBuffer", [[ArrayBufferData]]: dataCopy, [[ArrayBufferByteLength]]: size }に設定します。
それ以外の場合、valueが[[ViewedArrayBuffer]]内部スロットを持っている場合:
もしIsArrayBufferViewOutOfBounds(value)
がtrueである場合、"DataCloneError" DOMExceptionをスローします。
bufferをvalueの[[ViewedArrayBuffer]]内部スロットの値に設定します。
bufferSerializedを?StructuredSerializeInternal(buffer, forStorage, memory)に設定します。
Assert: bufferSerialized.[[Type]]が"ArrayBuffer", "ResizableArrayBuffer", "SharedArrayBuffer", または "GrowableSharedArrayBuffer"であることを確認します。
もしvalueが[[DataView]]内部スロットを持っている場合、serializedを{ [[Type]]: "ArrayBufferView", [[Constructor]]: "DataView", [[ArrayBufferSerialized]]: bufferSerialized, [[ByteLength]]: value.[[ByteLength]], [[ByteOffset]]: value.[[ByteOffset]] }に設定します。
それ以外の場合:
Assert: valueが[[TypedArrayName]] 内部スロットを持っていることを確認します。
serializedを{ [[Type]]: "ArrayBufferView", [[Constructor]]: value.[[TypedArrayName]], [[ArrayBufferSerialized]]: bufferSerialized, [[ByteLength]]: value.[[ByteLength]], [[ByteOffset]]: value.[[ByteOffset]], [[ArrayLength]]: value.[[ArrayLength]] }に設定します。
それ以外の場合、valueが[[MapData]]内部スロットを持っている場合:
serializedを{ [[Type]]: "Map", [[MapData]]: 新しい空のリスト }に設定します。
deepをtrueに設定します。
それ以外の場合、valueが[[SetData]]内部スロットを持っている場合:
serializedを{ [[Type]]: "Set", [[SetData]]: 新しい空のリスト }に設定します。
deepをtrueに設定します。
それ以外の場合、valueが[[ErrorData]]内部スロットを持ち、valueがプラットフォームオブジェクトでない場合:
nameを?Get(value, "name")に設定します。
もしnameが"Error", "EvalError", "RangeError", "ReferenceError", "SyntaxError", "TypeError", または"URIError"のいずれでもない場合、nameを"Error"に設定します。
valueMessageDescを?value.[[GetOwnProperty]]("message")に設定します。
もしIsDataDescriptor(valueMessageDesc) がfalseである場合、messageをundefinedに設定し、そうでない場合は?ToString(valueMessageDesc.[[Value]])に設定します。
serializedを{ [[Type]]: "Error", [[Name]]: name, [[Message]]: message }に設定します。
ユーザーエージェントは、stackプロパティなどのまだ指定されていない興味深い付随データのシリアル化された表現をserializedに添付するべきです。
このデータの指定に関する進行中の作業については、Error Stacks提案を参照してください。[JSERRORSTACKS]
それ以外の場合、valueが配列の異常オブジェクトである場合:
valueLenDescriptorを?OrdinaryGetOwnProperty(value,
"length")に設定します。
valueLenをvalueLenDescriptor.[[Value]]に設定します。
serializedを{ [[Type]]: "Array", [[Length]]: valueLen, [[Properties]]: 新しい空のリスト }に設定します。
deepをtrueに設定します。
それ以外の場合、valueがプラットフォームオブジェクトであり、それがシリアル化可能オブジェクトである場合:
もしvalueが[[Detached]]内部スロットを持ち、その値がtrueである場合、"DataCloneError" DOMExceptionをスローします。
typeStringをvalueの主要なインターフェースの識別子に設定します。
serializedを{ [[Type]]: typeString }に設定します。
deepをtrueに設定します。
それ以外の場合、valueがプラットフォームオブジェクトである場合、"DataCloneError" DOMExceptionをスローします。
それ以外の場合、もしIsCallable(value)がtrueである場合、"DataCloneError" DOMExceptionをスローします。
それ以外の場合、もしvalueが[[Prototype]],
[[Extensible]], または[[PrivateElements]]以外の内部スロットを持っている場合、"DataCloneError"
DOMExceptionをスローします。
たとえば、[[PromiseState]]や[[WeakMapData]]内部スロット。
それ以外の場合、valueが異常なオブジェクトであり、valueが任意の%Object.prototype%に関連付けられた固有のオブジェクトでない場合、
"DataCloneError" DOMExceptionをスローします。
たとえば、プロキシオブジェクト。
それ以外の場合:
serializedを{ [[Type]]: "Object", [[Properties]]: 新しい空のリスト }に設定します。
deepをtrueに設定します。
%Object.prototype%はこのステップとその後のステップによって処理されます。最終的な結果として、その異常性は無視され、デシリアル化後は空のオブジェクト(不変プロトタイプの異常オブジェクトではない)となります。
Set memory[value]を serializedに設定します。
もしdeepがtrueである場合:
もしvalueが[[MapData]]内部スロットを持っている場合:
copiedListを新しい空のリストに設定します。
各 レコード { [[Key]], [[Value]] } entryをvalue.[[MapData]]から実行します:
copiedEntryを新しいレコード { [[Key]]: entry.[[Key]], [[Value]]: entry.[[Value]] }に設定します。
もしcopiedEntry.[[Key]]が特別な値emptyでない場合、copiedEntryをcopiedListに追加します。
各 レコード { [[Key]], [[Value]] } entryをcopiedListから実行します:
serializedKeyを?StructuredSerializeInternal(entry.[[Key]], forStorage, memory)に設定します。
serializedValueを?StructuredSerializeInternal(entry.[[Value]], forStorage, memory)に設定します。
追加します { [[Key]]: serializedKey, [[Value]]: serializedValue }をserialized.[[MapData]]に。
それ以外の場合、valueが[[SetData]]内部スロットを持っている場合:
それ以外の場合、valueがプラットフォームオブジェクトであり、シリアル化可能オブジェクトである場合、valueのシリアル化手順をvalueの主要なインターフェースに基づいて実行し、serializedおよびforStorageを考慮して実行します。
シリアル化手順ではサブシリアル化を行う必要がある場合があります。これは、値subValueを入力として受け取り、StructuredSerializeInternal(subValue, forStorage, memory)を返す操作です。(言い換えれば、サブシリアル化は、この呼び出し内で一貫性を持たせるためにStructuredSerializeInternalを特化したものです。)
それ以外の場合、!EnumerableOwnProperties(value, key)内の各keyについて:
もし!HasOwnProperty(value, key) がtrueである場合:
inputValueを?value.[[Get]](key, value)に設定します。
outputValueを?StructuredSerializeInternal(inputValue, forStorage, memory)に設定します。
追加します { [[Key]]: key, [[Value]]: outputValue }をserialized.[[Properties]]に。
serializedを返します。
RecordはStructuredSerializeInternalによって生成される際に、他のレコードへの「ポインタ」を含み、循環参照を作成する可能性があることを理解することが重要です。例えば、次のJavaScriptオブジェクトをStructuredSerializeInternalに渡すとき:
const o = {};
o. myself = o;
次の結果が生成されます:
{
[[Type]]: "Object",
[[Properties]]: «
{
[[Key]]: "myself",
[[Value]]: <a pointer to this whole structure>
}
»
}
?StructuredSerializeInternal(value, false)を返します。
? StructuredSerializeInternal(value, true)を返します。
構造化デシリアライズ抽象操作は、レコードserializedを入力として受け取り、これが以前にStructuredSerializeまたはStructuredSerializeForStorageによって生成されたものであれば、それをtargetRealmに作成された新しいJavaScript値にデシリアライズします。
このプロセスは、特にArrayBufferオブジェクトのような新しいオブジェクトのメモリを確保しようとしたときに、例外をスローする可能性があります。
もしmemoryが提供されていない場合、memoryを空のマップとします。
このmemoryマップの目的は、オブジェクトを二重にデシリアライズしないようにすることです。これにより、グラフ内の重複オブジェクトの循環とアイデンティティが保持されます。
もしmemory[serialized]が存在する場合、memory[serialized]を返します。
deepをfalseに設定します。
valueを未初期化の値に設定します。
もしserialized.[[Type]]が"primitive"である場合、valueをserialized.[[Value]]に設定します。
それ以外の場合、もしserialized.[[Type]]が"Boolean"である場合、valueをtargetRealmに新たに作成されたBooleanオブジェクトに設定し、その[[BooleanData]]内部スロットの値をserialized.[[BooleanData]]に設定します。
それ以外の場合、もしserialized.[[Type]]が"Number"である場合、valueをtargetRealmに新たに作成されたNumberオブジェクトに設定し、その[[NumberData]]内部スロットの値をserialized.[[NumberData]]に設定します。
それ以外の場合、もしserialized.[[Type]]が"BigInt"である場合、valueをtargetRealmに新たに作成されたBigIntオブジェクトに設定し、その[[BigIntData]]内部スロットの値をserialized.[[BigIntData]]に設定します。
それ以外の場合、もしserialized.[[Type]]が"String"である場合、valueをtargetRealmに新たに作成されたStringオブジェクトに設定し、その[[StringData]]内部スロットの値をserialized.[[StringData]]に設定します。
それ以外の場合、もしserialized.[[Type]]が"Date"である場合、valueをtargetRealmに新たに作成されたDateオブジェクトに設定し、その[[DateValue]]内部スロットの値をserialized.[[DateValue]]に設定します。
それ以外の場合、もしserialized.[[Type]]が"RegExp"である場合、valueをtargetRealmに新たに作成されたRegExpオブジェクトに設定し、その[[RegExpMatcher]]内部スロットの値をserialized.[[RegExpMatcher]]に、[[OriginalSource]]内部スロットの値をserialized.[[OriginalSource]]に、[[OriginalFlags]]内部スロットの値をserialized.[[OriginalFlags]]に設定します。
それ以外の場合、もしserialized.[[Type]]が"SharedArrayBuffer"である場合:
もしtargetRealmの対応するエージェントクラスタがserialized.[[AgentCluster]]と異なる場合、"DataCloneError" DOMExceptionをスローします。
それ以外の場合、valueをtargetRealmに新たに作成されたSharedArrayBufferオブジェクトに設定し、その[[ArrayBufferData]]内部スロットの値をserialized.[[ArrayBufferData]]に、[[ArrayBufferByteLength]]内部スロットの値をserialized.[[ArrayBufferByteLength]]に設定します。
それ以外の場合、もしserialized.[[Type]]が"GrowableSharedArrayBuffer"である場合:
もしtargetRealmの対応するエージェントクラスタがserialized.[[AgentCluster]]と異なる場合、"DataCloneError" DOMExceptionをスローします。
それ以外の場合、valueをtargetRealmに新たに作成されたSharedArrayBufferオブジェクトに設定し、その[[ArrayBufferData]]内部スロットの値をserialized.[[ArrayBufferData]]に、[[ArrayBufferByteLengthData]]内部スロットの値をserialized.[[ArrayBufferByteLengthData]]に、[[ArrayBufferMaxByteLength]]内部スロットの値をserialized.[[ArrayBufferMaxByteLength]]に設定します。
それ以外の場合、もしserialized.[[Type]]が"ArrayBuffer"である場合、valueをtargetRealmに新たに作成されたArrayBufferオブジェクトに設定し、その[[ArrayBufferData]]内部スロットの値をserialized.[[ArrayBufferData]]に、[[ArrayBufferByteLength]]内部スロットの値をserialized.[[ArrayBufferByteLength]]に設定します。
これが例外をスローした場合、それをキャッチし、その後"DataCloneError" DOMExceptionをスローします。
このステップは、ArrayBufferオブジェクトを作成するためのメモリが十分に利用できない場合、例外をスローする可能性があります。
それ以外の場合、もしserialized.[[Type]]が"ResizableArrayBuffer"である場合、valueをtargetRealmに新たに作成されたArrayBufferオブジェクトに設定し、その[[ArrayBufferData]]内部スロットの値をserialized.[[ArrayBufferData]]に、[[ArrayBufferByteLength]]内部スロットの値をserialized.[[ArrayBufferByteLength]]に、[[ArrayBufferMaxByteLength]]内部スロットの値をserialized.[[ArrayBufferMaxByteLength]]に設定します。
これが例外をスローした場合、それをキャッチし、その後"DataCloneError" DOMExceptionをスローします。
このステップは、ArrayBufferオブジェクトを作成するためのメモリが十分に利用できない場合、例外をスローする可能性があります。
それ以外の場合、もしserialized.[[Type]]が"ArrayBufferView"である場合:
deserializedArrayBufferを?StructuredDeserialize(serialized.[[ArrayBufferSerialized]], targetRealm, memory)に設定します。
もしserialized.[[Constructor]]が"DataView"である場合、valueをtargetRealmに新たに作成されたDataViewオブジェクトに設定し、その[[ViewedArrayBuffer]]内部スロットの値をdeserializedArrayBufferに、[[ByteLength]]内部スロットの値をserialized.[[ByteLength]]に、[[ByteOffset]]内部スロットの値をserialized.[[ByteOffset]]に設定します。
それ以外の場合、valueをtargetRealmに新たに作成された型付き配列オブジェクトに設定し、serialized.[[Constructor]]によって指定されたコンストラクタを使用し、その[[ViewedArrayBuffer]]内部スロットの値をdeserializedArrayBufferに、[[TypedArrayName]]内部スロットの値をserialized.[[Constructor]]に、[[ByteLength]]内部スロットの値をserialized.[[ByteLength]]に、[[ByteOffset]]内部スロットの値をserialized.[[ByteOffset]]に、そして[[ArrayLength]]内部スロットの値をserialized.[[ArrayLength]]に設定します。
それ以外の場合、もしserialized.[[Type]]が"Map"である場合:
valueをtargetRealmに新たに作成されたMapオブジェクトに設定し、その[[MapData]]内部スロットの値を新しい空のリストに設定します。
deepをtrueに設定します。
それ以外の場合、もしserialized.[[Type]]が"Set"である場合:
valueをtargetRealmに新たに作成されたSetオブジェクトに設定し、その[[SetData]]内部スロットの値を新しい空のリストに設定します。
deepをtrueに設定します。
それ以外の場合、もしserialized.[[Type]]が"Array"である場合:
outputProtoをtargetRealm.[[Intrinsics]].[[%Array.prototype%]]に設定します。
valueを!ArrayCreate(serialized.[[Length]], outputProto)に設定します。
deepをtrueに設定します。
それ以外の場合、もしserialized.[[Type]]が"Object"である場合:
valueをtargetRealmに新たに作成されたオブジェクトに設定します。
deepをtrueに設定します。
それ以外の場合、もしserialized.[[Type]]が"Error"である場合:
prototypeを%Error.prototype%に設定します。
もしserialized.[[Name]]が"EvalError"である場合、prototypeを%EvalError.prototype%に設定します。
もしserialized.[[Name]]が"RangeError"である場合、prototype を%RangeError.prototype%に設定します。
もしserialized.[[Name]]が"ReferenceError"である場合、prototypeを%ReferenceError.prototype%に設定します。
もしserialized.[[Name]]が"SyntaxError"である場合、prototypeを%SyntaxError.prototype%に設定します。
もしserialized.[[Name]]が"TypeError"である場合、prototypeを%TypeError.prototype%に設定します。
もしserialized.[[Name]]が"URIError"である場合、prototypeを%URIError.prototype%に設定します。
messageをserialized.[[Message]]に設定します。
valueをOrdinaryObjectCreate(prototype, « [[ErrorData]] »)に設定します。
messageDescをプロパティディスクリプタ{ [[Value]]: message, [[Writable]]: true, [[Enumerable]]: false, [[Configurable]]: true }に設定します。
もしmessageが未定義でない場合、!OrdinaryDefineOwnProperty(value,
"message",
messageDesc)を実行します。
serializedに添付されたすべての関連データはデシリアライズされ、valueに添付されるべきです。
それ以外の場合:
interfaceNameをserialized.[[Type]]に設定します。
もしinterfaceNameで識別されたインターフェースがtargetRealmで公開されていない場合、"DataCloneError" DOMExceptionをスローします。
valueをinterfaceNameで識別されたインターフェースの新しいインスタンスに設定し、targetRealmで作成します。
deepをtrueに設定します。
設定 memory[serialized]をvalueにします。
もしdeepがtrueである場合:
もしserialized.[[Type]]が"Map"である場合:
各 レコード { [[Key]], [[Value]] } entryについて、serialized.[[MapData]]:
deserializedKeyを?StructuredDeserialize(entry.[[Key]], targetRealm, memory)に設定します。
deserializedValueを?StructuredDeserialize(entry.[[Value]], targetRealm, memory)に設定します。
追加 { [[Key]]: deserializedKey, [[Value]]: deserializedValue }をvalue.[[MapData]]に。
それ以外の場合、もしserialized.[[Type]]が"Set"である場合:
各 entryについて、 serialized.[[SetData]]:
deserializedEntryを?StructuredDeserialize(entry, targetRealm, memory)に設定します。
追加 deserializedEntry をvalue.[[SetData]]に。
それ以外の場合、もしserialized.[[Type]]が"Array"または"Object"である場合:
各 レコード { [[Key]], [[Value]] } entryについて、serialized.[[Properties]]:
deserializedValueを?StructuredDeserialize(entry.[[Value]], targetRealm, memory)に設定します。
resultを!CreateDataProperty(value, entry.[[Key]], deserializedValue)に設定します。
アサート: resultがtrueであること。
それ以外の場合:
インターフェース識別子serialized.[[Type]]に対応するデシリアライズ手順を実行します。指定された インターフェース、serialized、value、および targetRealmに対して行います。
デシリアライズ手順 は、サブデシリアライズを実行する必要があるかもしれません。これは、入力として以前にシリアライズされたレコードsubSerializedを取り、それをStructuredDeserialize(subSerialized, targetRealm, memory)として返します。 (言い換えれば、サブデシリアライズはStructuredDeserializeの特殊化であり、 この呼び出し内で一貫して行われることを保証します。)
valueを返します。
memoryを空のマップに設定します。
通常のStructuredSerializeInternalの使用法に加えて、 このアルゴリズムでは、memoryはtransferList内のアイテムを無視し、 代わりに独自の処理を行うためにも使用されます。
各transferableに対して、 transferList内の要素について実行します:
もしtransferableが[[ArrayBufferData]]内部スロットを持たず、
[[Detached]]内部スロットも持っていない場合、
"DataCloneError" DOMExceptionをスローします。
もしtransferableが[[ArrayBufferData]]内部スロットを持ち、かつIsSharedArrayBuffer(transferable)がtrueである場合、
"DataCloneError" DOMExceptionをスローします。
もしmemory[transferable]が存在する場合、
"DataCloneError" DOMExceptionをスローします。
設定 memory[transferable]を{ [[Type]]: 未初期化の値 }にします。
transferableはまだ転送されていません。転送には副作用が伴い、StructuredSerializeInternalがまず例外をスローできるようにする必要があります。
serializedを?StructuredSerializeInternal(value, false, memory)に設定します。
transferDataHoldersを新しい空のリストに設定します。
各transferableに対して、 transferList内の要素について実行します:
もしtransferableが[[ArrayBufferData]]内部スロットを持ち、
IsDetachedBuffer(transferable)がtrueである場合、
"DataCloneError" DOMExceptionをスローします。
もしtransferableが[[Detached]]内部スロットを持ち、transferable.[[Detached]]がtrueである場合、
"DataCloneError" DOMExceptionをスローします。
dataHolderをmemory[transferable]に設定します。
もしtransferableが[[ArrayBufferData]]内部スロットを持つ場合:
もしtransferableが[[ArrayBufferMaxByteLength]]内部スロットを持つ場合:
dataHolder.[[Type]]を"ResizableArrayBuffer"に設定します。
dataHolder.[[ArrayBufferData]]をtransferable.[[ArrayBufferData]]に設定します。
dataHolder.[[ArrayBufferByteLength]]をtransferable.[[ArrayBufferByteLength]]に設定します。
dataHolder.[[ArrayBufferMaxByteLength]]をtransferable.[[ArrayBufferMaxByteLength]]に設定します。
それ以外の場合:
dataHolder.[[Type]]を"ArrayBuffer"に設定します。
dataHolder.[[ArrayBufferData]]をtransferable.[[ArrayBufferData]]に設定します。
dataHolder.[[ArrayBufferByteLength]]をtransferable.[[ArrayBufferByteLength]]に設定します。
?DetachArrayBuffer(transferable)を実行します。
仕様は[[ArrayBufferDetachKey]]内部スロットを使用してArrayBufferがデタッチされないようにすることができます。これは、例えば WebAssembly JavaScript Interfaceで使用されます。[WASMJS]
それ以外の場合:
アサート: transferableはプラットフォームオブジェクトであり、 転送可能なオブジェクトです。
interfaceNameをtransferableのプライマリインターフェース の識別子に設定します。
dataHolder.[[Type]]をinterfaceNameに設定します。
指定されたインターフェースinterfaceNameに対応する転送手順をtransferableと dataHolderを使用して実行します。
transferable.[[Detached]]をtrueに設定します。
追加 dataHolderをtransferDataHoldersに。
{ [[Serialized]]: serialized, [[TransferDataHolders]]: transferDataHolders }を返します。
memoryを空のマップに設定します。
StructuredSerializeWithTransfer と同様に、通常のStructuredDeserializeでの使用方法に加えて、 このアルゴリズムでは、memoryが serializeWithTransferResult.[[TransferDataHolders]]内の項目を無視し、 独自の処理を行うためにも使用されます。
transferredValuesを新しい空のリストに設定します。
各 transferDataHolderに対して、 serializeWithTransferResult.[[TransferDataHolders]]内の要素について実行します:
valueを未初期化の値に設定します。
もしtransferDataHolder.[[Type]]が"ArrayBuffer"である場合、 valueをtargetRealm内の新しいArrayBufferオブジェクトに設定し、 その[[ArrayBufferData]]内部スロットの値をtransferDataHolder.[[ArrayBufferData]]に、 その[[ArrayBufferByteLength]]内部スロットの値をtransferDataHolder.[[ArrayBufferByteLength]]に設定します。
[[ArrayBufferData]]がデシリアライズ中にアクセス可能な場合、元のメモリが そのまま新しいArrayBufferに移されるため、新しいメモリの割り当てが必要ないため、 このステップで例外がスローされる可能性は低いです。例えば、ソースおよびターゲットの レルムが同じプロセス内にある場合などです。
それ以外の場合、もしtransferDataHolder.[[Type]]が"ResizableArrayBuffer"である場合、 valueをtargetRealm内の新しいArrayBufferオブジェクトに設定し、 その[[ArrayBufferData]]内部スロットの値を transferDataHolder.[[ArrayBufferData]]に、 その[[ArrayBufferByteLength]]内部スロットの値を transferDataHolder.[[ArrayBufferByteLength]]に、 そして[[ArrayBufferMaxByteLength]]内部スロットの値を transferDataHolder.[[ArrayBufferMaxByteLength]]に設定します。
前述の理由と同様に、このステップでも例外がスローされる可能性は低いです。
それ以外の場合:
interfaceNameをtransferDataHolder.[[Type]]に設定します。
もしinterfaceNameで識別されたインターフェースが
targetRealmに公開されていない場合、
"DataCloneError"
DOMExceptionをスローします。
valueをinterfaceNameで識別されたインターフェースの targetRealm内で作成された新しいインスタンスに設定します。
指定されたインターフェースinterfaceNameに対応する受信転送手順 をtransferDataHolderとvalueを使用して実行します。
設定 memory[transferDataHolder]を valueに。
追加 valueを transferredValuesに。
deserializedを? StructuredDeserialize(serializeWithTransferResult.[[Serialized]], targetRealm, memory)に設定します。
{ [[Deserialized]]: deserialized, [[TransferredValues]]: transferredValues }を返します。
他の仕様では、ここで定義された抽象操作を使用することができます。以下は、各抽象操作が通常どのような場合に有用であるかについてのガイドラインと例を提供します。
別のrealmに値を転送リストと共にクローンするが、ターゲットrealmが事前に知られていない場合。この場合、シリアライズステップは即座に実行でき、デシリアライズステップはターゲットrealmが判明するまで遅らせることができます。
messagePort.postMessage()はこの一対の抽象操作を使用しますが、MessagePortが出荷されるまで、宛先のrealmは知られません。
特定の値のRealmに依存しないスナップショットを作成し、それを無期限に保存し、後で再度JavaScriptの値として具現化することができ、場合によっては複数回行うことができます。
StructuredSerializeForStorageは、シリアライズされたデータがRealm間で渡されるのではなく、永続的に保存されることが予想される場合に使用できます。共有メモリを保存することには意味がないため、SharedArrayBufferオブジェクトをシリアライズしようとするとエラーが発生します。同様に、forStorage引数がtrueの場合、カスタムシリアライズ手順を持つプラットフォームオブジェクトが渡されたときに、エラーが発生するか、異なる動作をする可能性があります。
history.pushState()やhistory.replaceState()は、提供された状態オブジェクトに対してStructuredSerializeForStorageを使用し、それを適切なセッション履歴エントリにシリアライズされた状態として保存します。そして、StructuredDeserializeが使用され、history.stateプロパティが、最初に提供された状態オブジェクトのクローンを返せるようにします。
broadcastChannel.postMessage()は、入力にStructuredSerializeを使用し、結果に対してStructuredDeserializeを複数回使用し、ブロードキャストされる各宛先に新しいクローンを生成します。複数の宛先がある状況では転送は意味がないことに注意してください。
JavaScriptの値をファイルシステムに永続化するAPIは、入力に対してStructuredSerializeForStorageを使用し、出力に対してStructuredDeserializeを使用します。
一般的に、呼び出し側はJavaScript値の代わりにWeb IDL値を渡すことができ、その際はこれらのアルゴリズムを呼び出す前に暗黙の変換が行われると理解されます。
ユーザーエージェントメソッドに同期的にコールバックされる結果として呼び出されない呼び出しサイトは、StructuredSerialize、StructuredSerializeForStorage、またはStructuredSerializeWithTransfer抽象操作を実行する前に、スクリプトを実行する準備をしっかりと行い、コールバックを実行する準備をしっかりと行う必要があります。これは、シリアライズプロセスが最終的な深いシリアライズステップの一部として作成者定義のアクセサを呼び出す可能性があり、これらのアクセサが、entryとincumbentの概念が適切にセットアップされていることに依存する操作を呼び出す可能性があるためです。
window.postMessage()はその引数に対してStructuredSerializeWithTransferを実行しますが、アルゴリズムの同期部分内で即座にそれを行うため、このアルゴリズムを使用してもスクリプトを実行する準備やコールバックを実行する準備をする必要はありません。
対照的に、ある著者提供オブジェクトを定期的にStructuredSerializeを使ってシリアライズする仮想APIが、タスクをイベントループ上で直接実行する場合、適切な準備を事前に行う必要があります。現在のところ、プラットフォーム上でそのようなAPIは存在しませんが、通常は、著者コードの同期結果として、前もってシリアライズを実行する方が簡単です。
result = self.structuredClone(value[, { transfer }])
入力値を取得し、構造化クローンアルゴリズムを実行することでディープコピーを返します。転送可能オブジェクトがtransfer配列にリストされている場合、それらは単にクローンされるのではなく転送されます。つまり、それらは入力値内で使用できなくなります。
入力値の一部がシリアライズ可能でない場合は、"DataCloneError"DOMExceptionをスローします。
現在のすべてのエンジンでサポートされています。
structuredClone(value, options)
メソッドの手順は次のとおりです:
serializedをStructuredSerializeWithTransfer(value,
options["transfer"])に設定します。
deserializeRecordをStructuredDeserializeWithTransfer(serialized, thisの関連するrealm)に設定します。
deserializeRecord.[[Deserialized]]を返します。
HTML UA内のすべてのXMLおよびHTML文書は、Documentオブジェクトによって表されます。[DOM]
DocumentオブジェクトのURLは、DOMで定義されています。これは、Documentオブジェクトが作成される際に初期設定されますが、その後のDocumentオブジェクトのライフサイクル中に変更されることがあります。例えば、ユーザーがページ上のフラグメントにナビゲートしたときや、pushState()メソッドが新しいURLで呼び出されたときに変更されます。[DOM]
インタラクティブなユーザーエージェントは、通常DocumentオブジェクトのURLをユーザーインターフェイスに表示します。これは、サイトが別のサイトになりすましているかどうかをユーザーが確認する主な手段です。
DocumentオブジェクトのオリジンはDOMで定義されています。これは、Documentオブジェクトが作成される際に初期設定され、その後のDocumentのライフサイクル中にdocument.domainを設定することによってのみ変更されることがあります。Documentのオリジンは、そのURLのオリジンとは異なる場合があります。例えば、子ナビゲーブルが作成され、そのアクティブな文書のオリジンが親のアクティブな文書のオリジンを継承する場合、アクティブな文書のURLがabout:blankである場合があります。[DOM]
DocumentがcreateDocument()またはcreateHTMLDocument()メソッドを使用してスクリプトによって作成される場合、Documentはすぐにポストロードタスクの準備が整います。
文書のリファラーは、Documentが作成されるときに設定できる文字列(URLを表す)です。明示的に設定されていない場合、その値は空文字列です。
Documentオブジェクトすべての現在のエンジンでサポートされています。
DOM は、この仕様が大幅に拡張する Document
インターフェイスを定義しています。
enum DocumentReadyState { "loading" , "interactive" , "complete" };
enum DocumentVisibilityState { "visible" , "hidden" };
typedef (HTMLScriptElement or SVGScriptElement ) HTMLOrSVGScriptElement ;
[LegacyOverrideBuiltIns ]
partial interface Document {
static Document parseHTMLUnsafe ((TrustedHTML or DOMString ) html );
// resource metadata management
[PutForwards =href , LegacyUnforgeable ] readonly attribute Location ? location ;
attribute USVString domain ;
readonly attribute USVString referrer ;
attribute USVString cookie ;
readonly attribute DOMString lastModified ;
readonly attribute DocumentReadyState readyState ;
// DOM tree accessors
getter object (DOMString name );
[CEReactions ] attribute DOMString title ;
[CEReactions ] attribute DOMString dir ;
[CEReactions ] attribute HTMLElement ? body ;
readonly attribute HTMLHeadElement ? head ;
[SameObject ] readonly attribute HTMLCollection images ;
[SameObject ] readonly attribute HTMLCollection embeds ;
[SameObject ] readonly attribute HTMLCollection plugins ;
[SameObject ] readonly attribute HTMLCollection links ;
[SameObject ] readonly attribute HTMLCollection forms ;
[SameObject ] readonly attribute HTMLCollection scripts ;
NodeList getElementsByName (DOMString elementName );
readonly attribute HTMLOrSVGScriptElement ? currentScript ; // classic scripts in a document tree only
// dynamic markup insertion
[CEReactions ] Document open (optional DOMString unused1 , optional DOMString unused2 ); // both arguments are ignored
WindowProxy ? open (USVString url , DOMString name , DOMString features );
[CEReactions ] undefined close ();
[CEReactions ] undefined write ((TrustedHTML or DOMString )... text );
[CEReactions ] undefined writeln ((TrustedHTML or DOMString )... text );
// user interaction
readonly attribute WindowProxy ? defaultView ;
boolean hasFocus ();
[CEReactions ] attribute DOMString designMode ;
[CEReactions ] boolean execCommand (DOMString commandId , optional boolean showUI = false , optional DOMString value = "");
boolean queryCommandEnabled (DOMString commandId );
boolean queryCommandIndeterm (DOMString commandId );
boolean queryCommandState (DOMString commandId );
boolean queryCommandSupported (DOMString commandId );
DOMString queryCommandValue (DOMString commandId );
readonly attribute boolean hidden ;
readonly attribute DocumentVisibilityState visibilityState ;
// special event handler IDL attributes that only apply to Document objects
[LegacyLenientThis ] attribute EventHandler onreadystatechange ;
attribute EventHandler onvisibilitychange ;
// also has obsolete members
};
Document includes GlobalEventHandlers ;
Documentごとにポリシーコンテナ(ポリシーコンテナ)があり、最初は新しいポリシーコンテナであり、Documentに適用されるポリシーを含みます。
Documentごとに権限ポリシーがあり、これは権限ポリシーであり、最初は空です。
Documentごとにモジュールマップがあり、これはモジュールマップであり、最初は空です。
Documentごとにクロスオリジンオープナーポリシーがあり、これはクロスオリジンオープナーポリシーであり、最初は新しいクロスオリジンオープナーポリシーです。
Documentごとに初期about:blankフラグがあり、これはブール値で、最初はfalseです。
DocumentごとにWebDriver BiDiの読み込み中のナビゲーションIDがあり、これはナビゲーションIDまたはnullであり、最初はnullです。
名前が示すように、これはWebDriver BiDi仕様とのインターフェースに使用され、このDocumentを作成したナビゲーションが進行中のナビゲーションであったときに使用された元のナビゲーションIDに結び付けられる方法で、Documentのライフサイクルの初期段階で発生する特定の出来事について通知する必要があります。これは最終的に、WebDriver
BiDiが読み込みプロセスを終了と見なした後にnullに戻されます。[BIDI]
DocumentごとにaboutベースURLがあり、これはURLまたはnullで、最初はnullです。
これは「about:」スキームを持つDocumentにのみ設定されます。
DocumentごとにDOMミューテーションイベントフラグがあり、これはブール値で、最初はtrueです。
これは通常発生する場合にDOMミューテーションイベントの発生を抑制することを目的としています。ミューテーションイベントを説明する仕様は積極的に維持されていないため、このフラグを考慮しませんが、実装はあたかも考慮したかのように動作することが期待されています。[UIEVENTS]
Documentごとにbfcacheブロッキングの詳細があり、これはセットであり、復元されなかった理由の詳細が含まれ、最初は空です。
DocumentOrShadowRootインターフェイスDOMはDocumentOrShadowRootミックスインを定義しており、この仕様はそれを拡張します。
partial interface mixin DocumentOrShadowRoot {
readonly attribute Element ? activeElement ;
};
document.referrer
すべての現在のエンジンでサポートされています。
ユーザーがこのページにナビゲートした元のDocumentのURLを返します。ただし、ブロックされているか、元のドキュメントが存在しない場合は、空の文字列を返します。
noreferrerリンクタイプを使用して、リファラーをブロックすることができます。
referrer属性は文書のリファラーを返さなければなりません。
document.cookie [ = value ]
Documentに適用されるHTTPクッキーを返します。クッキーが存在しない場合や、このリソースに適用できない場合は、空の文字列が返されます。
クッキーを設定することができ、要素のHTTPクッキーセットに新しいクッキーを追加します。
内容がiframeでsandbox属性を持つ場合など、不透明なオリジンにサンドボックス化されている場合、取得および設定時に"SecurityError" DOMExceptionがスローされます。
すべての現在のエンジンでサポートされています。
cookie属性は、文書のURLで特定されたリソースのクッキーを表します。
以下のいずれかの条件に該当するDocumentオブジェクトは、クッキーに非対応のDocumentオブジェクトです:
DocumentオブジェクトDocumentのURLのスキームがHTTP(S)スキームではない
取得時に、ドキュメントがクッキー回避
Documentオブジェクトである場合、ユーザーエージェントは空の文字列を返さなければなりません。そうでない場合、Documentのオリジンが不透明なオリジンである場合、ユーザーエージェントは"SecurityError"DOMExceptionをスローしなければなりません。そうでない場合、ユーザーエージェントはドキュメントのURLに対してクッキー文字列を、"非HTTP" API用にBOMなしUTF-8デコードを使用して返さなければなりません。[COOKIES]
設定時に、文書がクッキーに非対応のDocumentオブジェクトである場合、ユーザーエージェントは何もしないでください。それ以外の場合、文書のオリジンが不透明なオリジンである場合、ユーザーエージェントは"SecurityError" DOMExceptionをスローしなければなりません。それ以外の場合、ユーザーエージェントは、文書のURLに対して新しい値を含むSet-Cookie文字列を受信したときと同様に、BOMなしでUTF-8エンコードされた値を使用して、非HTTP API経由で操作する必要があります。[COOKIES] [ENCODING]
cookie属性はフレームを超えてアクセス可能であるため、クッキーのパス制限は、サイトのどの部分にどのクッキーが送信されるかを管理するためのツールであり、セキュリティ機能ではありません。
cookie属性のゲッターとセッターは、共有状態に同期的にアクセスします。ロック機構がないため、マルチプロセスユーザーエージェントの他のブラウジングコンテキストがスクリプト実行中にクッキーを変更する可能性があります。例えば、サイトがクッキーを読み取り、その値を増加させ、次にそれを再設定し、その新しいクッキーの値をセッションの一意識別子として使用しようとした場合、同時に2つの異なるブラウザウィンドウでこれを行うと、両方のセッションに同じ「一意」の識別子を使用してしまう可能性があり、結果的に重大な影響を及ぼす可能性があります。
document.lastModified
すべての現在のエンジンでサポートされています。
ドキュメントの最終変更日をサーバーから報告された形式で、ユーザーのローカルタイムゾーンで"MM/DD/YYYY hh:mm:ss"の形式で返します。
最終変更日が不明な場合、代わりに現在の時刻が返されます。
lastModified属性は、取得時にDocumentのソースファイルの最終変更日時をユーザーのローカルタイムゾーンで次の形式で返さなければなりません。
日付の月の部分。
U+002F SOLIDUS文字(/)。
日付の日の部分。
U+002F SOLIDUS文字(/)。
日付の年の部分。
U+0020 SPACE文字。
時刻の時間の部分。
U+003A COLON文字(:)。
時刻の分の部分。
U+003A COLON文字(:)。
時刻の秒の部分。
上記の数値部分(年を除く)はすべて、必要に応じてゼロパディングされた2桁のASCII数字で10進数を表さなければなりません。年は、必要に応じてゼロパディングされた4桁以上の最短の文字列として、10進数を表すASCII数字として表さなければなりません。
Documentのソースファイルの最終変更日時は、使用されるネットワーキングプロトコルの関連機能、例としてドキュメントのHTTP
`Last-Modified`
ヘッダーの値や、ローカルファイルのファイルシステム内のメタデータから派生させなければなりません。最終変更日時が不明な場合、この属性は上記の形式で現在の日時を返さなければなりません。
document.readyState
Documentが読み込み中の場合は"loading"、パースが完了しサブリソースの読み込みが続いている場合は"interactive"、すべて読み込みが完了した場合は"complete"を返します。
この値が変わると、readystatechangeイベントがDocumentオブジェクトで発生します。
DOMContentLoadedイベントは、"interactive"に遷移した後、"complete"に遷移する前に、async属性を持つscript要素以外のすべてのサブリソースが読み込まれた時点で発生します。
すべての現在のエンジンでサポートされています。
各Documentは、現在のドキュメントの準備状態を持ちます。これは文字列で、初期状態は"complete"です。
「Document」オブジェクトを作成および初期化する
アルゴリズムを介して作成されたDocumentオブジェクトの場合、どのスクリプトもdocument.readyStateの値を確認する前に、この値はすぐに「loading」にリセットされます。
このデフォルトは、初期about:blank Documentオブジェクトや、ブラウジングコンテキストを持たないDocumentオブジェクトにも適用されます。
readyStateのゲッターステップは、thisの現在のドキュメントの準備状態を返すことです。
DocumentdocumentのreadinessValueを現在のドキュメントの準備状態を更新するには:
documentの現在のドキュメントの準備状態がreadinessValueと等しい場合は、リターンします。
documentの現在のドキュメントの準備状態をreadinessValueに設定します。
documentがHTMLパーサーに関連付けられている場合:
nowを、現在の高精度時間をdocumentの関連するグローバルオブジェクトに基づいて取得します。
readinessValueが"complete"であり、documentのロードタイミング情報のDOM完了時間が0である場合、documentのロードタイミング情報のDOM完了時間をnowに設定します。
それ以外の場合で、readinessValueが"interactive"であり、documentのロードタイミング情報のDOMインタラクティブ時間が0である場合、documentのロードタイミング情報のDOMインタラクティブ時間をnowに設定します。
イベントを発火します。名前はreadystatechangeです。documentで発生します。
Documentは、HTMLパーサーまたはXMLパーサーに関連付けられており、まだ停止または中断されていない場合、アクティブパーサーを持っていると言われます。
Documentはドキュメントのロードタイミング情報ロードタイミング情報を持っています。
Documentは、ドキュメントのアンロードタイミング情報前のドキュメントアンロードタイミングを持っています。
Documentは、クロスオリジンリダイレクトによって作成されたというブール値を持ちます。初期状態はfalseです。
ドキュメントのロードタイミング情報構造体には、以下の項目があります。
DOMHighResTimeStamp値
ドキュメントのアンロードタイミング情報構造体には、以下の項目があります。
DOMHighResTimeStamp値
各Documentは、最初は空のセットであるレンダーブロッキング要素セット(セット)を持ちます。
次の条件が成立する場合、Document
documentはレンダーブロッキング要素を追加することができます。
documentのコンテンツタイプが「text/html」であり、documentのボディ要素がnullである場合です。
次の条件が両方とも真である場合、Document
documentはレンダーブロックされます。
documentのレンダーブロッキング要素セットが空でない、またはdocumentがレンダーブロッキング要素を追加することを許可している。
要素elは、elのノードドキュメント documentがレンダーブロックされている場合、かつelがdocumentのレンダーブロッキング要素セットに含まれている場合、レンダーブロッキングと見なされます。
要素elに対してレンダーブロッキングを行うには:
elのノードドキュメントをdocumentとします。
もしdocumentがレンダーブロッキング要素を追加することを許可している場合は、セットに追加します。elをdocumentのレンダーブロッキング要素セットに追加します。
要素elに対してレンダーブロックを解除するには:
elのノードドキュメントをdocumentとします。
削除します。elをdocumentのレンダーブロッキング要素セットから削除します。
あるレンダーブロッキング要素elがブラウジングコンテキストとの接続が切れるか、elのブロッキング属性の値が変更されてelがもはや潜在的にレンダーブロッキングでなくなる場合、レンダーブロックを解除します。
文書のhtml要素は、html要素であればその文書要素となり、そうでなければnullです。
document.head
現在のすべてのエンジンでサポートされています。
head要素を返します。
文書のhead要素は、head要素が存在すれば、html要素の最初の子であり、そうでなければnullです。
head属性は、取得時に、文書のhead要素(head要素またはnull)を返さなければなりません。
document.title [ = value ]
文書のタイトルを返します。HTMLではtitle要素によって、SVGではSVGのtitle要素によって定義されます。
設定することもでき、文書のタイトルを更新します。適切な要素が存在しない場合、新しい値は無視されます。
文書のtitle要素は、文書内で最初に現れるtitle要素(ツリー順)であり、存在しない場合はnullです。
現在のすべてのエンジンでサポートされています。
title属性は、取得時に次のアルゴリズムを実行しなければなりません:
もし文書要素がSVGsvg要素である場合、valueを最初のSVGtitle要素の子テキストコンテンツに設定します。
それ以外の場合、valueを最初のtitle要素の子テキストコンテンツに設定し、title要素がnullの場合は空文字列に設定します。
valueを返します。
設定時に、次のリストで最初に一致する条件に対応するステップを実行する必要があります:
svg要素である場合
何もしません。
document.body [ = value ]
現在のすべてのエンジンでサポートされています。
body要素を返します。
設定することもでき、body要素を置き換えます。
新しい値がbody要素やframeset要素でない場合は、"HierarchyRequestError" DOMExceptionをスローします。
文書のbody要素は、html要素の子の中で最初に現れるbody要素またはframeset要素であり、該当する要素がない場合はnullです。
body属性は、取得時に、文書のbody要素(body要素またはframeset要素、もしくはnull)を返さなければなりません。設定時には、次のアルゴリズムを実行する必要があります:
body要素やframeset要素でない場合、"HierarchyRequestError" DOMExceptionをスローします。
HierarchyRequestError" DOMExceptionをスローします。
getterによって返されるbody属性の値は、必ずしもsetterに渡されたものとは限りません。
この例では、セッターが正常にbody要素を挿入します(ただし、これは非準拠です。SVG
はSVG
svgの子としてbodyを許可していないため)。しかし、ゲッターはドキュメント要素がhtmlでないため、nullを返します。
< svg xmlns = "http://www.w3.org/2000/svg" >
< script >
document. body = document. createElementNS( "http://www.w3.org/1999/xhtml" , "body" );
console. assert( document. body === null );
</ script >
</ svg >
document.images
すべての現在のエンジンでサポートされています。
HTML ドキュメント内の img 要素の
HTMLCollection
を返します。
document.embeds
すべての現在のエンジンでサポートされています。
document.plugins
すべての現在のエンジンでサポートされています。
HTML ドキュメント内の embed
要素の HTMLCollection
を返します。
document.links
すべての現在のエンジンでサポートされています。
HTML ドキュメント内の a および area 要素の HTMLCollection
を返します。これらの要素は href 属性を持ちます。
document.forms
すべての現在のエンジンでサポートされています。
HTML ドキュメント内の form 要素の
HTMLCollection
を返します。
document.scripts
すべての現在のエンジンでサポートされています。
HTML ドキュメント内の script 要素の HTMLCollection
を返します。
images 属性は、Document ノードにルート化された HTMLCollection
を返す必要があります。このフィルタは、img
要素にのみ一致します。
embeds 属性は、Document ノードにルート化された HTMLCollection
を返す必要があります。このフィルタは、embed
要素にのみ一致します。
plugins 属性は、embeds
属性によって返されるものと同じオブジェクトを返す必要があります。
links 属性は、Document ノードにルート化された HTMLCollection
を返す必要があります。このフィルタは、a 要素の href 属性および area 要素の href 属性にのみ一致します。
forms 属性は、Document ノードにルート化された HTMLCollection
を返す必要があります。このフィルタは、form
要素にのみ一致します。
scripts 属性は、Document ノードにルート化された HTMLCollection
を返す必要があります。このフィルタは、script 要素にのみ一致します。
collection = document.getElementsByName(name)
現在のすべてのエンジンでサポートされています。
getElementsByName(elementName) メソッドは、指定された
elementName 値を持つ要素を含む、ライブの NodeList
を返します。この NodeList は、ツリー順に並べられた、name 属性が elementName 引数と同一であるすべての HTML
要素 から構成されます。Document
オブジェクトで同じ引数を指定してメソッドを再度呼び出すと、ユーザーエージェントは以前の呼び出しで返されたオブジェクトと同じものを返すことがあります。それ以外の場合、新しい NodeList
オブジェクトを返す必要があります。
document.currentScript
現在のすべてのエンジンでサポートされています。
クラシックスクリプト を表す限り、現在実行中の script 要素、または SVG script
要素を返します。再入可能なスクリプト実行の場合、まだ実行が完了していないスクリプトの中で最も最近実行を開始したものを返します。
Document が現在 script 要素や SVG script 要素を実行していない場合 (例:
実行中のスクリプトがイベントハンドラやタイムアウトであるため)、または現在実行中の script 要素や SVG script 要素が モジュールスクリプト を表す場合は、null を返します。
currentScript
属性は、取得時に最後に設定された値を返さなければなりません。Document
が作成されるとき、currentScript
は null に初期化されなければなりません。
この API は、script 要素や SVG script 要素をグローバルに公開するため、実装者および標準化コミュニティでの支持を失っています。そのため、モジュールスクリプト を実行するときや、シャドウツリー
内でスクリプトを実行するときなど、新しいコンテキストでは利用できません。このようなコンテキストで実行中のスクリプトを識別する新しいソリューションを作成することを検討していますが、それはグローバルに公開されないようにする予定です:
issue #1013 を参照してください。
Document
インターフェースは、名前付きプロパティ
をサポートします。任意の時点で Document オブジェクト
document の サポートされるプロパティ名 は、後の重複を無視して、それらを提供する要素に従って ツリー順 で構成され、同じ要素が両方に寄与する場合は、id 属性からの値が name
属性からの値よりも前に来るものとします。
公開された embed, form, iframe, img, および 公開された object 要素で、非空の
name コンテンツ属性を持ち、document を ルート
としているドキュメントツリーに存在するもの;
非空の id
コンテンツ属性を持ち、document を ルート としているドキュメントツリーに存在する
公開された object 要素; および
非空の id コンテンツ属性と非空の
name コンテンツ属性の両方を持ち、document を ルート としているドキュメントツリーに存在する
img 要素。
名前付きプロパティ name の値を Document
に対して決定するために、ユーザーエージェントは次の手順を使用して取得された値を返す必要があります。
elements を、Document を ルート とするドキュメントツリー内で name という名前を持つ 名前付き要素
のリストとします。
アルゴリズムが Web IDL によって 呼び出されない限り、少なくとも1つの要素が存在します。
elements に要素が1つだけ含まれており、その要素が iframe 要素で、その
iframe 要素の コンテンツナビゲーブル が null でない場合、その要素の
アクティブな WindowProxy を返します。
それ以外の場合、elements に要素が1つだけ含まれている場合、その要素を返します。
それ以外の場合、name という名前を持つ 名前付き要素 のみを一致させるフィルタを持つ HTMLCollection
を Document ノードにルート化されたものとして返します。
名前付き要素は、上記のアルゴリズムの目的において、以下のいずれかに該当する要素です。
embed, form, iframe, img, または 公開された object
要素で、name という名前を持つ name コンテンツ属性を持つもの、または
object
要素で、name という名前を持つ id コンテンツ属性を持つもの、または
img 要素で、name
という名前を持つ id
コンテンツ属性を持ち、かつ非空の name コンテンツ属性を併せ持つもの。
embed 要素または object 要素は、公開された 先祖が存在せず、object
要素において、フォールバックコンテンツを表示していないか、object または embed 子孫が存在しない場合に 公開された とみなされます。
dir 属性は、Document インターフェース上で、dir コンテンツ属性とともに定義されています。
HTMLの要素、属性、および属性値は、この仕様によって特定の意味(セマンティクス)を持つように定義されています。例えば、ol要素は順序付きリストを表し、
lang属性はコンテンツの言語を表します。
これらの定義により、Webブラウザや検索エンジンなどのHTMLプロセッサが、作成者が考慮していなかったさまざまな文脈でドキュメントやアプリケーションを表示および利用できるようになります。
単純な例として、デスクトップコンピュータのWebブラウザのみを考慮して作成されたWebページを考えてみましょう:
<!DOCTYPE HTML>
< html lang = "en" >
< head >
< title > My Page</ title >
</ head >
< body >
< h1 > Welcome to my page</ h1 >
< p > I like cars and lorries and have a big Jeep!</ p >
< h2 > Where I live</ h2 >
< p > I live in a small hut on a mountain!</ p >
</ body >
</ html >
HTMLは意味を伝えるものであり、見た目を表現するものではないため、同じページが小さなモバイルフォンのブラウザでも利用できます。例えば、デスクトップで見出しが大きな文字で表示される場合でも、モバイルフォンのブラウザではページ全体で同じサイズの文字を使用し、見出しは太字で表示されるかもしれません。
さらに、画面サイズの違いだけでなく、同じページを視覚障害者が音声合成をベースにしたブラウザを使用して閲覧することもできます。この場合、ページは画面に表示されるのではなく、例えばヘッドホンを通じて音声でユーザーに読み上げられます。見出しには大きな文字を使用する代わりに、音声ブラウザでは異なる音量や遅い速度の声を使用することがあります。
それだけではありません。ブラウザはページのどの部分が見出しであるかを知っているため、ユーザーがドキュメントを迅速に移動できるようなドキュメントアウトラインを作成し、「次の見出しにジャンプ」や「前の見出しにジャンプ」するキーを使用して、ページ内をすばやく移動できる機能を提供することができます。これらの機能は、特に音声ブラウザで一般的であり、ユーザーがページをすばやく移動するのが難しい場合に便利です。
ブラウザを超えても、この情報は活用されます。検索エンジンは見出しを使用してページを効果的にインデックス化したり、検索結果からページ内のサブセクションへのクイックリンクを提供したりすることができます。ツールは見出しを使用して目次を作成することができ、この仕様の目次も実際にはそのように生成されています。
この例では見出しに焦点を当てましたが、同じ原則がHTML内のすべてのセマンティクスに適用されます。
作成者は、要素、属性、または属性値を、それらの適切なセマンティックな目的以外の目的で使用してはなりません。そうすると、ソフトウェアがページを正しく処理できなくなるからです。
例えば、以下のコードスニペットは、企業サイトの見出しを表すことを意図していますが、2行目はサブセクションの見出しとしてではなく、単にサブヘッディングまたはサブタイトル(同じセクションの補助的な見出し)として表示されるため、非準拠です。
< body >
< h1 > ACME Corporation</ h1 >
< h2 > The leaders in arbitrary fast delivery since 1920</ h2 >
...
このような状況にはhgroup要素を使用することができます:
< body >
< hgroup >
< h1 > ACME Corporation</ h1 >
< p > The leaders in arbitrary fast delivery since 1920</ p >
</ hgroup >
...
次の例では、文法的には正しいにもかかわらず、セルに配置されたデータが明らかに表形式データではなく、cite要素が誤用されているため、同様に非準拠です:
<!DOCTYPE HTML>
< html lang = "en-GB" >
< head > < title > Demonstration </ title > </ head >
</ body >
< table >
< tr > < td > My favourite animal is the cat. </ td > </ tr >
< tr >
< td >
—< a href = "https://example.org/~ernest/" >< cite > Ernest</ cite ></ a > ,
in an essay from 1992
</ td >
</ tr > </ table > </ body > </ html >
これにより、これらのセマンティクスに依存するソフトウェアが誤動作することになります。例えば、視覚障害者がドキュメント内の表をナビゲートできる音声ブラウザは、上記の引用を表として報告し、ユーザーを混乱させるでしょう。同様に、ページから作品のタイトルを抽出するツールは、「Ernest」を作品のタイトルとして抽出してしまいますが、実際にはそれは作品のタイトルではなく人名です。
このドキュメントの修正バージョンは次のようになります:
<!DOCTYPE HTML>
< html lang = "en-GB" >
< head > < title > Demonstration </ title > </ head >
</ body >
< blockquote >
< p > My favourite animal is the cat. </ p >
</ blockquote >
< p >
—< a href = "https://example.org/~ernest/" > Ernest</ a > ,
in an essay from 1992
</ p > </ body > </ html >
作成者は、この仕様または他の適用可能な仕様によって許可されていない要素、属性、または属性値を使用してはなりません。そうすることは、将来的に言語を拡張することを著しく困難にします。
次の例では、非準拠の属性値「carpet」と、この仕様で許可されていない非準拠の属性「texture」が含まれています:
< label > Carpet: < input type = "carpet" name = "c" texture = "deep pile" ></ label >
このマークアップを正しくするための代替方法は次のとおりです:
< label > Carpet: < input type = "text" class = "carpet" name = "c" data-texture = "deep pile" ></ label >
DOMノードのノードドキュメントの閲覧コンテキストがnullである場合、 HTML構文の要件およびXML構文の要件を除き、すべてのドキュメント適合性要件が免除されます。
特に、template要素のtemplateコンテンツのノードドキュメントの閲覧コンテキストは
nullです。例えば、コンテンツモデルの要件や、属性値のマイクロ構文要件はtemplate要素のtemplateコンテンツには適用されません。この例では、img要素が、template要素外では無効となるプレースホルダを持つ属性値を持っています。
< template >
< article >
< img src = "{{src}}" alt = "{{alt}}" >
< h1 ></ h1 >
</ article >
</ template >
ただし、上記のマークアップで</h1>終了タグを省略すると、それはHTML構文の違反となり、適合性チェッカーによってエラーとしてフラグが立てられます。
スクリプトやその他のメカニズムを使用することで、ユーザーエージェントが処理中に、属性、テキスト、さらにはドキュメント全体の構造が動的に変化することがあります。ドキュメントの任意の瞬間におけるセマンティクスは、その瞬間のドキュメントの状態によって表され、そのためドキュメントのセマンティクスは時間とともに変化する可能性があります。ユーザーエージェントはこれが発生すると、ドキュメントの表示を更新しなければなりません。
HTMLにはprogress要素があり、プログレスバーを表します。その「value」属性がスクリプトによって動的に更新された場合、ユーザーエージェントは進行状況が変化していることを表示するためにレンダリングを更新します。
DOM内のHTML要素を表すノードは、この仕様の関連セクションにリストされているインターフェースを実装し、スクリプトに公開しなければなりません。これには、HTML要素がXMLドキュメント内にある場合も含まれます。これらのドキュメントが別のコンテキストにある場合(例: XSLT変換内)でも同様です。
DOM内の要素は、物事を表現します。つまり、それらはセマンティクスとして知られる固有の意味を持っています。
例えば、ol要素は順序付きリストを表します。
要素は、明示的または暗黙的に参照(言及)されることがあります。DOM内の要素を明示的に参照する1つの方法は、その要素にid属性を付与し、そのid属性の値をフラグメントとして使用してハイパーリンクを作成することです。ただし、参照にはハイパーリンクは必須ではありません。要素を指す方法であれば何でもかまいません。
次のfigure要素を考えてみましょう。この要素にはid属性が付与されています:
< figure id = "module-script-graph" >
< img src = "module-script-graph.svg" alt = "Module A depends on module B, which depends on modules C and D." >
< figcaption > Figure 27: a simple module graph</ figcaption >
</ figure >
ハイパーリンクベースの参照は、次のようにa要素を使用して作成できます:
As we can see in < a href = "#module-script-graph" > figure 27</ a > , ...
しかし、figure要素を参照する方法は他にも多くあります。例えば次のようなものがあります:
"As depicted in the figure of modules A, B, C, and D..."
"In Figure 27..." (ハイパーリンクなしで)
"From the contents of the 'simple module graph' figure..."
"In the figure below..."(ただしこれは推奨されません)
すべてのHTML要素のインターフェースが継承し、追加の要件がない要素が使用しなければならない基本的なインターフェースは、HTMLElementインターフェースです。
現在のすべてのエンジンでサポートされています。
現在のすべてのエンジンでサポートされています。
[Exposed =Window ]
interface HTMLElement : Element {
[HTMLConstructor ] constructor ();
// metadata attributes
[CEReactions ] attribute DOMString title ;
[CEReactions ] attribute DOMString lang ;
[CEReactions ] attribute boolean translate ;
[CEReactions ] attribute DOMString dir ;
// user interaction
[CEReactions ] attribute (boolean or unrestricted double or DOMString )? hidden ;
[CEReactions ] attribute boolean inert ;
undefined click ();
[CEReactions ] attribute DOMString accessKey ;
readonly attribute DOMString accessKeyLabel ;
[CEReactions ] attribute boolean draggable ;
[CEReactions ] attribute boolean spellcheck ;
[CEReactions ] attribute DOMString writingSuggestions ;
[CEReactions ] attribute DOMString autocapitalize ;
[CEReactions ] attribute [LegacyNullToEmptyString ] DOMString innerText ;
[CEReactions ] attribute [LegacyNullToEmptyString ] DOMString outerText ;
ElementInternals attachInternals ();
// The popover API
undefined showPopover ();
undefined hidePopover ();
boolean togglePopover (optional boolean force );
[CEReactions ] attribute DOMString ? popover ;
};
HTMLElement includes GlobalEventHandlers ;
HTMLElement includes ElementContentEditable ;
HTMLElement includes HTMLOrSVGElement ;
[Exposed =Window ]
interface HTMLUnknownElement : HTMLElement {
// Note: intentionally no [HTMLConstructor]
};
HTMLElementインターフェースには、さまざまな機能に関連するメソッドや属性が含まれており、そのため、このインターフェースのメンバーはこの仕様書のさまざまなセクションで説明されています。
nameという名前を持つ要素の要素インターフェースは、HTML名前空間で次のように決定されます:
nameがapplet、bgsound、blink、isindex、keygen、multicol、nextid、またはspacerである場合、HTMLUnknownElementを返します。
nameがacronym、basefont、big、center、nobr、noembed、noframes、plaintext、rb、rtc、strike、またはttである場合、HTMLElementを返します。
nameがlistingまたはxmpである場合、HTMLPreElementを返します。
それ以外の場合、この仕様でnameというローカル名に対応する要素タイプに適したインターフェースが定義されている場合、そのインターフェースを返します。
他の適用可能な仕様でnameに適したインターフェースが定義されている場合、そのインターフェースを返します。
nameが有効なカスタム要素名である場合、HTMLElementを返します。
HTMLUnknownElementを返します。
有効なカスタム要素名の場合にHTMLElementを使用するのは、将来のアップグレードが、HTMLElementからサブクラスへの線形遷移のみを引き起こし、HTMLUnknownElementから無関係なサブクラスへの横方向の遷移を引き起こさないようにするためです。
HTMLとSVGの要素間で共有される機能には、HTMLOrSVGElementインターフェースミックスインが使用されます:
[SVG]
interface mixin HTMLOrSVGElement {
[SameObject ] readonly attribute DOMStringMap dataset ;
attribute DOMString nonce ; // intentionally no [CEReactions]
[CEReactions ] attribute boolean autofocus ;
[CEReactions ] attribute long tabIndex ;
undefined focus (optional FocusOptions options = {});
undefined blur ();
};
HTMLでもSVGでもない要素の例としては、次のように作成されるものがあります:
const el = document.createElementNS("some namespace", "example");
console.assert(el.constructor === Element);
カスタム要素機能をサポートするために、すべてのHTML要素には特別なコンストラクタ動作があります。これは、[HTMLConstructor]IDL拡張属性で示されます。これにより、以下に詳述されているように、特定のインターフェースオブジェクトが呼び出されたときに特定の動作を行うことが示されています。
[HTMLConstructor]拡張属性は引数を取らず、コンストラクタ操作にのみ表示される必要があります。これは、コンストラクタ操作に1回だけ表示され、インターフェースには、注釈付きのコンストラクタ操作のみが含まれ、他の操作は含まれない必要があります。注釈付きのコンストラクタ操作は、引数を取らないように宣言されなければなりません。
[HTMLConstructor]拡張属性で注釈されたコンストラクタ操作で宣言されたインターフェースには、次のオーバーライドされたコンストラクタステップがあります:
registryを現在のグローバルオブジェクトのCustomElementRegistryオブジェクトとします。
NewTargetがアクティブ関数オブジェクトと等しい場合、TypeErrorをスローします。
これは、カスタム要素がコンストラクタとして要素インターフェースを使用して定義されている場合に発生します:
customElements. define( "bad-1" , HTMLButtonElement);
new HTMLButtonElement(); // (1)
document. createElement( "bad-1" ); // (2)
この場合、HTMLButtonElementの実行中に(明示的に(1)のように、または暗黙的に(2)のように)、アクティブ関数オブジェクトとNewTargetはどちらもHTMLButtonElementです。このチェックがなければ、HTMLButtonElementのインスタンスをbad-1というローカル名で作成することが可能になります。
definitionをregistry内のコンストラクタがNewTargetに等しいエントリとします。そのような定義がない場合、TypeErrorをスローします。
registry内にはundefinedのコンストラクタを持つエントリが存在しないため、このステップは、HTML要素のコンストラクタが関数として呼び出されることも防ぎます(この場合、NewTargetはundefinedになります)。
is valueをnullにします。
もしdefinitionのローカル名がdefinitionの名前と等しい場合(すなわち、definitionが自律カスタム要素のためのものである場合)、次のようにします:
アクティブ関数オブジェクトがHTMLElementでない場合、TypeErrorをスローします。
これは、カスタム要素がローカル名を拡張しないように定義されているが、HTMLElementでないクラスから継承している場合に発生します:
customElements. define( "bad-2" , class Bad2 extends HTMLParagraphElement {});
この場合、Bad2のインスタンスを構築する際に発生する(暗黙的な)super()呼び出し中に、アクティブ関数オブジェクトはHTMLParagraphElementであり、HTMLElementではありません。
それ以外の場合(すなわち、definitionがカスタマイズされた組み込み要素のためのものである場合):
valid local namesを、この仕様または他の適用可能な仕様で定義されたローカル名のリストとし、それがアクティブ関数オブジェクトを要素インターフェースとして使用します。
valid local namesがdefinitionのローカル名を含まない場合、TypeErrorをスローします。
これは、カスタム要素が特定のローカル名を拡張するように定義されているが、間違ったクラスから継承している場合に発生します:
customElements. define( "bad-3" , class Bad3 extends HTMLQuoteElement {}, { extends : "p" });
この場合、Bad3のインスタンスを構築する際に発生する(暗黙的な)super()呼び出し中に、valid local
namesにはqとblockquoteが含まれていますが、definitionのローカル名はpであり、そのリストには含まれていません。
is valueをdefinitionの名前に設定します。
もしdefinitionの構築スタックが空であれば、次のようにします:
elementをインターフェースを実装する新しいオブジェクトを内部的に作成することの結果とし、現在の領域とNewTargetを与えます。
elementのノードドキュメントを現在のグローバルオブジェクトの関連するDocumentに設定します。
elementの名前空間プレフィックスをnullに設定します。
elementのカスタム要素の状態を"custom"に設定します。
elementのカスタム要素定義をdefinitionに設定します。
elementのis valueをis
valueに設定します。
elementを返します。
これは、作成者スクリプトがnew MyCustomElement()のようにして直接新しいカスタム要素を構築する場合に発生します。
もしType(prototype)がオブジェクトでない場合、次のようにします:
realmを?GetFunctionRealm(NewTarget)に設定します。
prototypeを、インターフェースプロトタイプオブジェクトのrealmに設定し、そのインターフェースがアクティブ関数オブジェクトのインターフェースと同じであるものとします。
アクティブ関数オブジェクトの領域はrealmでない可能性があるため、私たちは領域を超えて「同じインターフェース」という一般的な概念を使用しています。インターフェースオブジェクトの等価性を探しているわけではありません。このフォールバック動作には、NewTargetの領域を使用し、適切なプロトタイプをそこに見つけることが含まれ、これはJavaScriptビルトインおよびWebIDLのインターフェースを実装する新しいオブジェクトを内部的に作成するアルゴリズムに類似した動作に一致するように設計されています。
elementをdefinitionの構築スタックの最後のエントリとします。
elementが既に構築済みのマーカーである場合、TypeErrorをスローします。
これは、作成者コードがカスタム要素コンストラクタ内で非準拠である場合に発生します。例えば、super()を呼び出す前に、構築中のクラスの別のインスタンスを作成する場合などです:
let doSillyThing = true ;
class DontDoThis extends HTMLElement {
constructor() {
if ( doSillyThing) {
doSillyThing = false ;
new DontDoThis(); // Now the construction stack will contain an already constructed marker.
}
// This will then fail with a TypeError:
super ();
}
}
これはまた、作成者コードがカスタム要素コンストラクタ内で非準拠であり、super()を2回呼び出す場合にも発生します。JavaScript仕様によれば、これは実際にはスーパークラスのコンストラクタ(すなわちこのアルゴリズム)を2回実行した後、エラーをスローします:
class DontDoThisEither extends HTMLElement {
constructor() {
super ();
// This will throw, but not until it has already called into the HTMLElement constructor
super ();
}
}
?element.[[SetPrototypeOf]](prototype)を実行します。
definitionの構築スタックの最後のエントリを既に構築済みのマーカーに置き換えます。
elementを返します。
このステップは通常、カスタム要素をアップグレードする際に達成されます。既存の要素が返され、カスタム要素コンストラクタ内のsuper()呼び出しが、その既存の要素をthisに割り当てます。
[HTMLConstructor]によって暗示されるコンストラクタ動作に加えて、いくつかの要素には名前付きコンストラクタもあります(これらは実際にはprototypeプロパティが変更されたファクトリ関数です)。
HTML要素の名前付きコンストラクタは、カスタム要素コンストラクタを定義する際にextends句で使用することもできます:
class AutoEmbiggenedImage extends Image {
constructor( width, height) {
super ( width * 10 , height * 10 );
}
}
customElements. define( "auto-embiggened" , AutoEmbiggenedImage, { extends : "img" });
const image = new AutoEmbiggenedImage( 15 , 20 );
console. assert( image. width === 150 );
console. assert( image. height === 200 );
この仕様書の各要素には、以下の情報を含む定義があります:
要素が使用される場所についての非規範的な説明です。この情報は、この要素を子として許可する要素のコンテンツモデルと重複しており、あくまで便宜のために提供されています。
簡単にするために、最も具体的な期待のみがリストされています。
例えば、すべてのフレージングコンテンツはフローコンテンツです。したがって、フレージングコンテンツである要素は、"フレージングコンテンツが期待される場所"としてのみリストされます。これは、より具体的な期待事項だからです。フローコンテンツが期待される場所では、フレージングコンテンツも期待され、その期待に応えることができます。
要素の子および子孫として含まれるべきコンテンツの規範的な説明です。
text/html構文で、開始および終了タグが省略できるかどうかについての非規範的な説明です。この情報は、省略可能なタグセクションで示される規範的要件と重複しており、便宜のために要素定義内で提供されています。
要素に指定できる属性の規範的なリスト(禁止されていない限り)、およびそれらの属性に関する非規範的な説明です。(ダッシュの左側の内容が規範的であり、右側の内容は規範的ではありません。)
作成者向け: ARIAのrole属性およびaria-*属性の使用に関する適合要件は、ARIA in HTMLで定義されています。[ARIA] [ARIAHTML]
実装者向け: アクセシビリティAPIのセマンティクスを実装するためのユーザーエージェントの要件は、HTML Accessibility API Mappingsに定義されています。[HTMLAAM]
その要素が実装しなければならないDOMインターフェースの規範的な定義です。
次に、その要素が表現する内容、および作成者や実装に適用される追加の規範的な適合基準の説明が続きます。例が含まれることもあります。
属性値は文字列です。特に指定がない限り、HTML要素の属性値は空の文字列を含む任意の文字列であり、そのような属性値に指定できるテキストに制限はありません。
この仕様で定義された各要素には、要素の期待されるコンテンツの説明であるコンテンツモデルがあります。HTML要素は、その要素のコンテンツモデルに記載された要件に一致するコンテンツを持たなければなりません。要素のコンテンツとは、DOM内のその要素の子要素を指します。
ASCIIホワイトスペースは、要素間では常に許可されています。ユーザーエージェントは、ソースマークアップ内の要素間にあるこれらの文字を、DOM内のテキストノードとして表現します。空のテキストノードや、それらの文字のみで構成されるテキストノードは、要素間ホワイトスペースと見なされます。
要素間ホワイトスペース、コメントノード、および処理命令ノードは、要素のコンテンツがその要素のコンテンツモデルに一致するかどうかを判断する際には無視されなければならず、文書や要素のセマンティクスを定義するアルゴリズムに従う際にも無視されなければなりません。
したがって、要素Aが他の要素Bによって前後に置かれているとされるのは、AとBが同じ親ノードを持ち、他の要素ノードやテキストノード(要素間ホワイトスペース以外)がそれらの間に存在しない場合です。同様に、要素が唯一の子であるとされるのは、その要素が要素間ホワイトスペース、コメントノード、および処理命令ノード以外の他のノードを含まない場合です。
作成者は、HTML要素を、各要素に定義された場所や他の仕様書で明示的に要求される場所以外のどこにも使用してはなりません。XML複合文書の場合、これらのコンテキストは、関連するコンテキストを提供するように定義された他の名前空間の要素内にある場合があります。
The Atom Syndication
Formatはcontent要素を定義しています。そのtype属性がxhtmlの値を持つ場合、The Atom
Syndication Formatはそれに単一のHTMLdiv要素を含むことを要求します。したがって、div要素はそのコンテキストで許可されていますが、これはこの仕様書で明示的に規範的に記述されているわけではありません。[ATOM]
さらに、HTML要素は親ノードを持たない孤立ノードである場合があります。
たとえば、td要素を作成し、スクリプト内のグローバル変数に保存することは、td要素が通常はtr要素内でのみ使用されるべきであるにもかかわらず、適合しています。
var data = {
name: "Banana" ,
cell: document. createElement( 'td' ),
};
要素のコンテンツモデルが何も含まないの場合、その要素にはテキストノード(要素間ホワイトスペースを除く)や要素ノードを含めてはなりません。
コンテンツモデルが「何も含まない」ほとんどのHTML要素は、便宜上、空要素(終了タグを持たない要素)でもあります。しかし、これらは完全に別の概念です。
HTMLの各要素は、似た特性を持つ要素をまとめる1つ以上のカテゴリに属します。この仕様書では、以下の広範なカテゴリが使用されています:
一部の要素は、この仕様書の他の部分で定義される他のカテゴリにも属します。
これらのカテゴリは次のように関連しています:
セクショニングコンテンツ、見出しコンテンツ、フレージングコンテンツ、埋め込みコンテンツ、およびインタラクティブコンテンツはすべてフローコンテンツの一種です。メタデータは時にはフローコンテンツです。メタデータとインタラクティブコンテンツは時にはフレージングコンテンツです。埋め込みコンテンツはフレージングコンテンツの一種でもあり、時にはインタラクティブコンテンツでもあります。
その他のカテゴリも特定の目的のために使用されます。例えば、フォームコントロールは、共通の要件を定義するためにいくつかのカテゴリを使用して指定されています。一部の要素には独自の要件があり、特定のカテゴリには該当しません。
メタデータコンテンツは、他のコンテンツの表示や動作を設定したり、ドキュメントと他のドキュメントとの関係を設定したり、他の「帯域外」情報を伝達するコンテンツです。
主にメタデータ関連のセマンティクスを持つ他の名前空間の要素(例: RDF)もメタデータコンテンツです。
したがって、XMLシリアル化では、次のようにRDFを使用できます:
< html xmlns = "http://www.w3.org/1999/xhtml"
xmlns:r = "http://www.w3.org/1999/02/22-rdf-syntax-ns#" xml:lang = "en" >
< head >
< title > Hedral's Home Page</ title >
< r:RDF >
< Person xmlns = "http://www.w3.org/2000/10/swap/pim/contact#"
r:about = "https://hedral.example.com/#" >
< fullName > Cat Hedral</ fullName >
< mailbox r:resource = "mailto:hedral@damowmow.com" />
< personalTitle > Sir</ personalTitle >
</ Person >
</ r:RDF >
</ head >
< body >
< h1 > My home page</ h1 >
< p > I like playing with string, I guess. Sister says squirrels are fun
too so sometimes I follow her to play with them.</ p >
</ body >
</ html >
ただし、HTMLシリアル化ではこれはできません。
文書やアプリケーションの本文で使用されるほとんどの要素は、フローコンテンツに分類されます。
a
abbr
address
area(それがmap要素の子孫である場合)
article
aside
audio
b
bdi
bdo
blockquote
br
button
canvas
cite
code
data
datalist
del
details
dfn
dialog
div
dl
em
embed
fieldset
figure
footer
form
h1
h2
h3
h4
h5
h6
header
hgroup
hr
i
iframe
img
input
ins
kbd
label
link(本文で許可されている場合)
main(階層的に正しいmain要素である場合)
map
mark
math
menu
meta(itemprop属性が存在する場合)
meter
nav
noscript
object
ol
output
p
picture
pre
progress
q
ruby
s
samp
script
search
section
select
slot
small
span
strong
sub
sup
svg
table
template
textarea
time
u
ul
var
video
wbr
区分化コンテンツは、headerおよびfooter要素の範囲を定義するコンテンツです。
見出しコンテンツは、セクションの見出しを定義します(区分化コンテンツ要素を使用して明示的にマークアップされているか、または見出しコンテンツ自体によって暗黙的に決定されます)。
フレージングコンテンツは、文書のテキストおよび段落内でそのテキストをマークアップする要素です。フレージングコンテンツのまとまりが段落を形成します。
a
abbr
area (if it is a
descendant
of a map element)
audio
b
bdi
bdo
br
button
canvas
cite
code
data
datalist
del
dfn
em
embed
i
iframe
img
input
ins
kbd
label
link (if it is allowed in the body)
map
mark
math
meta (if the itemprop
attribute is present)
meter
noscript
object
output
picture
progress
q
ruby
s
samp
script
select
slot
small
span
strong
sub
sup
svg
template
textarea
time
u
var
video
wbr
フレージングコンテンツとして分類された要素の多くは、フレージングコンテンツとして分類された要素しか含めることができず、フローコンテンツを含めることはできません。
テキストは、コンテンツモデルの文脈では、何もないか、テキストノードを意味します。テキストは単独でコンテンツモデルとして使用されることもありますが、フレージングコンテンツでもあり、要素間の空白(テキストノードが空であるか、ASCIIスペース文字のみが含まれている場合)にもなります。
テキストノードおよび属性値は、スカラー値でなければならず、非文字や制御文字(ただしASCIIスペース文字を除く)を含んではなりません。
この仕様には、テキストノードおよび属性値の正確な値に対して、文脈に応じた追加の制約が含まれています。
埋め込みコンテンツとは、別のリソースを文書に取り込むコンテンツや、他のボキャブラリーから文書に挿入されたコンテンツのことです。
HTML名前空間以外の名前空間からの要素で、メタデータではなくコンテンツを伝えるものは、この仕様で定義されたコンテンツモデルの目的のために、埋め込みコンテンツと見なされます。(例:MathMLやSVG。)
一部の埋め込みコンテンツ要素は、フォールバックコンテンツを持つことがあります。これは、外部リソースが使用できない場合(例:サポートされていないフォーマットであるため)に使用されるコンテンツです。要素定義には、フォールバックがある場合、その内容が記載されています。
インタラクティブコンテンツとは、ユーザーの操作を目的としたコンテンツです。
a(href属性がある場合)audio(controls属性がある場合)buttondetailsembediframeimg(usemap属性がある場合)
input(type属性が非表示状態ではない場合)
labelselecttextareavideo(controls属性がある場合)
一般的なルールとして、内容モデルがフローコンテンツまたは フレージングコンテンツのいずれかを許可する要素には、 属性が指定されていない、 少なくとも1つの内容が触知可能なコンテンツである必要があります。
触知可能なコンテンツは、要素に 空でない内容を提供することで、要素を非空にします。例えば、空でないテキストや、 ユーザーが聞くことができるaudio要素、または video、img、 またはcanvas要素など、見ることができるもの、あるいは他のインタラクティブなものです(例えば、インタラクティブなフォームコントロール)。
ただし、この要件は厳密な要件ではありません。スクリプトによって後で埋められるプレースホルダーとして要素が使用される場合や、 テンプレートの一部であり、多くのページでは埋められるが、特定のページでは関連性がない場合など、要素が正当な理由で空である場合が多々あります。
適合チェッカーは、著者支援としてこの要件を満たしていない要素を見つけるためのメカニズムを提供することが推奨されます。
次の要素は触知可能なコンテンツです:
aabbraddressarticleasideaudio(controls属性がある場合)bbdibdoblockquotebuttoncanvascitecodedatadeldetailsdfndivdl(要素の子に少なくとも1つの名前と値のグループが含まれている場合)
emembedfieldsetfigurefooterformh1
h2
h3
h4
h5
h6
headerhgroupiiframeimginput(type属性が非表示状態ではない場合)
inskbdlabelmainmapmarkmathmenu(要素の子に少なくとも1つのli要素が含まれている場合)meternavobjectol(要素の子に少なくとも1つのli要素が含まれている場合)outputppicturepreprogressqrubyssampsearchsectionselectsmallspanstrongsubsupsvgtabletextareatimeuul(要素の子に少なくとも1つのli要素が含まれている場合)varvideoスクリプト支援要素は、それ自体では何も表現しない(すなわち、表示されない)要素ですが、スクリプトをサポートするために使用されます。例えば、ユーザーのための機能を提供します。
以下の要素はスクリプト支援要素です:
一部の要素は透明と表現され、そのコンテンツモデルの説明に「透明」という用語が使用されています。透明な要素のコンテンツモデルは、その親要素のコンテンツモデルから派生します。「透明」な部分に必要な要素は、透明な要素が含まれている親要素のコンテンツモデルの該当部分で必要とされる要素と同じです。
例えば、ins要素がruby要素の内部にある場合、その中にrt要素を含めることはできません。これは、ruby要素のコンテンツモデルでins要素が許可されている部分がフレージングコンテンツを許可する部分であり、rt要素はフレージングコンテンツではないためです。
透明な要素が互いに入れ子になっている場合、このプロセスを反復的に適用する必要があります。
次のマークアップフラグメントを考えてみましょう:
< p >< object >< param >< ins >< map >< a href = "/" > Apples</ a ></ map ></ ins ></ object ></ p >
「Apples」がa要素の中に許可されているかどうかを確認するには、コンテンツモデルを調べます。a要素のコンテンツモデルは透明であり、map要素のコンテンツモデルも透明であり、ins要素のコンテンツモデルも透明であり、object要素内でins要素が見つかる部分も透明です。object要素はp要素の中にあり、そのコンテンツモデルはフレージングコンテンツです。したがって、「Apples」は許可されます。テキストはフレージングコンテンツだからです。
透明な要素に親要素がない場合、そのコンテンツモデルの「透明」な部分は、代わりにフローコンテンツを受け入れるものとして扱わなければなりません。
このセクションで定義されている段落という用語は、p要素の定義だけでなく、より広範な文書の解釈方法を説明するために使用されます。ここで定義される段落の概念は、段落をマークアップするためのいくつかの方法の一つに過ぎません。
段落は通常、特定のトピックを扱う1つまたは複数の文を含むブロックのテキストとして構成されるフレージングコンテンツの流れですが、一般的なテーマのグループ化にも使用されます。例えば、住所も段落と見なされるし、フォームの一部、署名、または詩のスタンザも同様です。
次の例では、セクション内に2つの段落があります。また、段落ではないフレージングコンテンツを含む見出しもあります。コメントや要素間の空白が段落を形成しないことに注意してください。
< section >
< h2 > 段落の例</ h2 >
これはこの例の< em > 最初の</ em > 段落です。
< p > これは2番目の段落です。</ p >
<!-- これは段落ではありません。 -->
</ section >
フローコンテンツ内の段落は、a、ins、del、およびmap要素が問題を複雑にすることなく、文書がどのように見えるかに基づいて定義されます。これらの要素はハイブリッドコンテンツモデルを持ち、段落の境界をまたぐことができます。以下の最初の2つの例がそのことを示しています。
一般的に、段落の境界をまたぐ要素を持つことは避けた方が良いです。そのようなマークアップを維持することは困難です。
次の例では、前の例のマークアップを取り、insおよびdel要素をいくつかのマークアップの周りに配置して、テキストが変更されたことを示しています(この場合、変更はあまり意味をなさないかもしれません)。この例は、insおよびdel要素が含まれていても、前の例と全く同じ段落を持っていることに注意してください。ins要素は見出しと最初の段落の境界をまたぎ、del要素は2つの段落の間の境界をまたいでいます。
< section >
< ins >< h2 > 段落の例</ h2 >
これはこの</ ins > 例の< em > 最初の</ em > 段落です< del > 。
< p > これは2番目の段落です。</ p ></ del >
<!-- これは段落ではありません。 -->
</ section >
viewを、文書内のa、ins、del、およびmap要素をそのコンテンツで置き換えたDOMのビューとします。次に、view内で、他のタイプのコンテンツで中断されないフレージングコンテンツノードの兄弟関係の各流れについて、その流れの最初のノードをfirst、最後のノードをlastとします。そのような流れのうち、少なくとも1つのノードが埋め込みコンテンツでも要素間の空白でもない場合、元のDOMにそのfirstの直前からlastの直後まで段落が存在します(したがって、段落はa、ins、del、およびmap要素をまたぐことができます)。
適合性チェックツールは、段落が互いに重なっているケースについて著者に警告を出すことができます(これは、object、video、audio、およびcanvas要素を使用する場合、また、HTMLをさらに埋め込むことができる他の名前空間の要素、例えばSVG
svgやMathML
mathなどで間接的に発生することがあります)。
p要素は、個々の段落をラップするために使用でき、そうでなければフレージングコンテンツ以外のコンテンツが段落を互いに区切ることがない場合に使用されます。
次の例では、リンクが最初の段落の半分、2つの段落を区切る見出しのすべて、および2番目の段落の半分にまたがっています。リンクは段落と見出しをまたいでいます。
< header >
Welcome!
< a href = "about.html" >
This is home of...
< h1 > The Falcons!</ h1 >
The Lockheed Martin multirole jet fighter aircraft!
</ a >
This page discusses the F-16 Fighting Falcon's innermost secrets.
</ header >
これを別の方法でマークアップし、今回は段落を明示的に示し、1つのリンク要素を3つに分割してみましょう:
< header >
< p > Welcome! < a href = "about.html" > This is home of...</ a ></ p >
< h1 >< a href = "about.html" > The Falcons!</ a ></ h1 >
< p >< a href = "about.html" > The Lockheed Martin multirole jet
fighter aircraft!</ a > This page discusses the F-16 Fighting
Falcon's innermost secrets.</ p >
</ header >
段落がフォールバックコンテンツを定義する特定の要素を使用している場合、段落が重なる可能性があります。例えば、次のセクションでは:
< section >
< h2 > 私の猫たち</ h2 >
あなたは私の猫シミュレーターで遊ぶことができます。
< object data = "cats.sim" >
猫シミュレーターを見るには、次のリンクのいずれかを使用してください:
< ul >
< li >< a href = "cats.sim" > シミュレーター ファイルをダウンロード</ a >
< li >< a href = "https://sims.example.com/watch?v=LYds5xY4INU" > オンライン シミュレーターを使用</ a >
</ ul >
または、Mellblom ブラウザーにアップグレードしてください。
</ object >
私はそれをとても誇りに思っています。
</ section >
5つの段落があります:
object要素を含む、「あなたは私の猫シミュレーターで遊ぶことができます。object
私はそれをとても誇りに思っています。」という段落。
最初の段落は他の4つと重なっています。「cats.sim」リソースをサポートするユーザーエージェントは最初の段落のみを表示しますが、フォールバックを表示するユーザーエージェントは、最初の段落の最初の文を2番目の段落と同じ段落内に表示し、最後の段落を最初の段落の2番目の文の先頭に表示するため、混乱を招きます。
この混乱を避けるためには、明示的なp要素を使用することができます。例えば:
< section >
< h2 > 私の猫たち</ h2 >
< p > あなたは私の猫シミュレーターで遊ぶことができます。</ p >
< object data = "cats.sim" >
< p > 猫シミュレーターを見るには、次のリンクのいずれかを使用してください。</ p >
< ul >
< li >< a href = "cats.sim" > シミュレーター ファイルをダウンロード</ a >
< li >< a href = "https://sims.example.com/watch?v=LYds5xY4INU" > オンライン シミュレーターを使用</ a >
</ ul >
< p > または、Mellblom ブラウザーにアップグレードしてください。</ p >
</ object >
< p > 私はそれをとても誇りに思っています。</ p >
</ section >
以下の属性はすべてのHTML要素に共通であり、この仕様で定義されていない要素にも指定できます:
accesskey
autocapitalize
autofocus
contenteditable
dir
draggable
enterkeyhint
inert
inputmode
is
itemid
itemprop
itemref
itemscope
itemtype
lang
nonce
popover
spellcheck
style
tabindex
title
translate
writingsuggestions
これらの属性は、この仕様でHTML要素の属性としてのみ定義されています。この仕様がこれらの属性を持つ要素について言及する場合、これらの属性を持つと定義されていない名前空間の要素は、これらの属性を持つ要素とは見なされません。
例えば、次のXMLフラグメントでは、"bogus"要素は、この仕様で定義されたdir属性を持っていませんが、dirという名前の属性を持っています。したがって、最内のspan要素の方向性は、div要素から間接的に継承された'rtl'です。
< div xmlns = "http://www.w3.org/1999/xhtml" dir = "rtl" >
< bogus xmlns = "https://example.net/ns" dir = "ltr" >
< span xmlns = "http://www.w3.org/1999/xhtml" >
</ span >
</ bogus >
</ div >
すべての現在のエンジンでサポートされています。
DOMは、任意の名前空間内の任意の要素に対して、class、id、およびslot属性のユーザーエージェント要件を定義します。[DOM]
class、id、およびslot属性は、すべてのHTML要素に指定できます。
HTML要素に指定された場合、class属性は、その要素が属するさまざまなクラスを表す空白で区切られたトークンのセットでなければなりません。
要素にクラスを割り当てると、CSSのセレクターでのクラスのマッチング、DOMのgetElementsByClassName()メソッド、およびその他の機能に影響を与えます。
class属性で使用できるトークンには追加の制限はありませんが、著者はコンテンツの性質を説明する値を使用することをお勧めします。
HTML要素に指定された場合、id属性の値は、要素のIDの中で一意でなければならず、少なくとも1文字を含んでいなければなりません。値にはASCII空白を含めてはなりません。
id属性は、その要素の一意の識別子(ID)を指定します。
IDの形式には他の制限はありません。特に、IDは数字だけで構成されたり、数字で始まったり、アンダースコアで始まったり、句読点だけで構成されたりすることができます。
要素の一意の識別子は、主にドキュメントの特定の部分にリンクする方法として、スクリプトで要素をターゲットにする方法として、またはCSSから特定の要素をスタイル設定する方法として使用されます。
識別子は不透明な文字列です。id属性の値から特定の意味を導き出してはなりません。
slot属性には、HTML要素に固有の適合要件はありません。
slot属性は、要素にスロットを割り当てるために使用されます。slot属性を持つ要素は、slot要素によって作成されたスロットに割り当てられます。そのslot要素がシャドウツリー内にあり、そのルートのホストが対応するslot属性値を持つ場合に限ります。
支援技術製品がHTML要素と属性よりも細かいインターフェースを公開できるようにするために、支援技術製品のための注釈を指定できます(ARIAのroleおよびaria-*属性)。[ARIA]
次のイベントハンドラーコンテンツ属性は、任意のHTML要素に指定できます:
onauxclick
onbeforeinput
onbeforematch
onbeforetoggle
onblur*
oncancel
oncanplay
oncanplaythrough
onchange
onclick
onclose
oncontextlost
oncontextmenu
oncontextrestored
oncopy
oncuechange
oncut
ondblclick
ondrag
ondragend
ondragenter
ondragleave
ondragover
ondragstart
ondrop
ondurationchange
onemptied
onended
onerror*
onfocus*
onformdata
oninput
oninvalid
onkeydown
onkeypress
onkeyup
onload*
onloadeddata
onloadedmetadata
onloadstart
onmousedown
onmouseenter
onmouseleave
onmousemove
onmouseout
onmouseover
onmouseup
onpaste
onpause
onplay
onplaying
onprogress
onratechange
onreset
onresize*
onscroll*
onscrollend*
onsecuritypolicyviolation
onseeked
onseeking
onselect
onslotchange
onstalled
onsubmit
onsuspend
ontimeupdate
ontoggle
onvolumechange
onwaiting
onwheel
アスタリスクが付いている属性は、body要素に指定された場合、同じ名前のWindowオブジェクトのイベントハンドラーを公開するため、異なる意味を持ちます。
これらの属性はすべての要素に適用されますが、すべての要素で有用というわけではありません。例えば、メディア要素だけが、ユーザーエージェントによって発生するvolumechangeイベントを受信することがあります。
カスタムデータ属性(例:data-foldernameまたはdata-msgid)は、ページに固有のカスタムデータ、状態、注釈などを保存するために、任意のHTML要素に指定できます。
HTMLドキュメントでは、HTML名前空間内の要素には、"http://www.w3.org/1999/xhtml"という正確な値を持つxmlns属性を指定できます。これはXMLドキュメントには適用されません。
HTMLでは、xmlns属性は全く効果がありません。それは基本的にお守りのようなものです。XMLへの移行やXMLからの移行を少しでも容易にするために許可されています。HTMLパーサーによって解析されると、その属性は名前空間には入らず、XMLの名前空間宣言属性のように"http://www.w3.org/2000/xmlns/"名前空間には入りません。
XMLでは、xmlns属性は名前空間宣言メカニズムの一部であり、要素にxmlns属性が指定されていない名前空間を持つことはできません。
XMLは、XML名前空間内の任意の要素に、xml:space属性を使用することも許可しています。この属性は、HTMLでは効果がなく、HTMLのデフォルトの動作は空白を保持することです。[XML]
HTML要素にtext/html構文でxml:space属性をシリアライズする方法はありません。
title 属性すべての現在のエンジンでサポートされています。
title属性は、要素に対する助言情報を表します。ツールチップに適したものである必要があります。リンクの場合、これがターゲットリソースのタイトルまたは説明である可能性があります。画像の場合、画像のクレジットまたは説明である可能性があります。段落の場合、脚注やテキストに対するコメントである可能性があります。引用の場合、ソースに関する追加情報である可能性があります。インタラクティブコンテンツの場合、それが要素のラベルや使用方法に関する指示である可能性があります。値はテキストです。
title属性に依存することは現在推奨されていません。多くのユーザーエージェントが、この仕様で要求されているように属性をアクセシブルな方法で公開しないためです(例えば、ツールチップを表示するにはマウスなどのポインティングデバイスが必要であり、キーボードのみのユーザーやモダンな電話やタブレットを使用しているタッチのみのユーザーを除外する可能性があります)。
この属性が要素に省略されている場合、それはこの属性が設定された最も近い祖先のHTML要素のtitle属性が、この要素にも関連していることを意味します。この属性を設定すると、祖先の助言情報がこの要素に関連していないことを明示的に示します。この属性を空の文字列に設定することは、この要素には助言情報がないことを示します。
title属性の値にU+000A LINE FEED
(LF)文字が含まれている場合、内容は複数の行に分割されます。各U+000A LINE FEED (LF)文字は改行を表します。
title属性で改行を使用する際には注意が必要です。
例えば、次のスニペットは実際には改行が含まれた省略語の展開を定義しています:
< p > 私のログは、今日HTTPにいくつかの関心があったことを示しています< abbr title = "Hypertext
Transport Protocol" > HTTP</ abbr > です。</ p >
いくつかの要素(link、abbr、inputなど)は、上記のセマンティクスを超えてtitle属性の追加のセマンティクスを定義しています。
要素の助言情報は、次のアルゴリズムが返す値です。このアルゴリズムが値を返すと、アルゴリズムは中断されます。アルゴリズムが空の文字列を返した場合、助言情報は存在しません。
ユーザーエージェントは、要素に助言情報がある場合、ユーザーに通知する必要があります。さもなければ、情報は発見できません。
すべての現在のエンジンでサポートされています。
titleIDL属性は、titleコンテンツ属性を反映する必要があります。
lang と xml:lang
属性すべての現在のエンジンでサポートされています。
lang属性(名前空間なし)は、要素の内容およびテキストを含む要素の属性の主な言語を指定します。その値は、有効な BCP
47 言語タグ、または空の文字列でなければなりません。この属性を空の文字列に設定することは、主な言語が不明であることを示します。[BCP47]
lang属性は、XML名前空間内に定義されています。[XML]
これらの属性が要素に省略された場合、この要素の言語は、親要素の言語と同じになります(もしあれば)(ただし、slot要素はシャドウツリー内の要素を除きます)。
名前空間なしのlang属性は、任意のHTML要素で使用できます。
lang属性は、XML 名前空間で、HTML 要素に使用でき、XML ドキュメントに使用できます。また、関連する仕様が許可する場合には、他の名前空間の要素にも使用できます(特に、MathML や SVG
は、lang 属性を、XML 名前空間で指定することを許可しています)。lang属性が名前空間に属さず、lang 属性が XML 名前空間に指定されている場合、同じ要素上でそれらは、ASCII
大文字小文字を区別しない 形で、完全に同じ値を持たなければなりません。
著者は、名前空間なしのlang属性をXML名前空間のHTML要素に対してHTMLドキュメントで使用してはなりません。XMLへの移行を容易にするために、著者は、名前空間なしの属性をプレフィックスなしで、リテラルのローカル名"xml:lang"でHTMLドキュメントのHTML要素に指定できますが、この属性は、名前空間なしのlang属性も指定されている場合にのみ指定する必要があります。両方の属性は、ASCII大文字と小文字を区別しない方法で比較される際に、同じ値を持っていなければなりません。
名前空間なしでプレフィックスなし、リテラルのローカル名"xml:lang"を持つ属性は、言語処理には何の影響もありません。
ノードの言語を決定するには、ユーザーエージェントは次のリストの最初の適切なステップを使用する必要があります:
lang属性を持つ要素である場合
その属性の値を使用します。
lang属性を持つ場合
その属性の値を使用します。
プラグマ設定のデフォルト言語が設定されている場合、それがノードの言語です。プラグマ設定のデフォルト言語が設定されていない場合、上位レベルのプロトコル(HTTPなど)からの言語情報(存在する場合)が最終的なフォールバック言語として使用されます。そのような言語情報がない場合、および上位レベルのプロトコルが複数の言語を報告する場合、ノードの言語は不明であり、対応する言語タグは空の文字列です。
結果の値が認識されない言語タグである場合、それは与えられた言語タグを持つ未知の言語として扱われ、他のすべての言語と区別されなければなりません。ラウンドトリップや言語タグを期待する他のサービスとの通信の目的で、ユーザーエージェントは未知の言語タグを修正せずに通過させ、BCP 47 言語タグとしてタグ付けする必要があります。そうすれば、後続のサービスがデータを別のタイプの言語記述として解釈することはありません。[BCP47]
例えば、lang="xyzzy"を持つ要素は、セレクタ:lang(xyzzy)(例:CSS)で一致しますが、:lang(abcde)では一致しません。どちらも同様に無効ですが、これも同様です。同様に、連携して動作するウェブブラウザとスクリーンリーダーが、要素の言語について通信する場合、ブラウザはスクリーンリーダーにその言語が
"xyzzy" であることを伝えます。たとえそれが無効であると知っていても、スクリーンリーダーがそのタグをサポートしている可能性があるためです。たとえスクリーンリーダーが BCP 47
と別の言語名エンコーディングの構文の両方をサポートしていて、その別の構文で "xyzzy" がベラルーシ語を表す方法であったとしても、BCP 47 でベラルーシ語が "be"
というコードで記述されているため、スクリーンリーダーがテキストをベラルーシ語として扱い始めるのは誤りです。
結果の値が空の文字列である場合、それはノードの言語が明確に不明であることを意味します。
ユーザーエージェントは、適切な処理やレンダリングを決定するために要素の言語を使用することがあります(例えば、適切なフォントや発音の選択、辞書の選択、日付ピッカーなどのフォームコントロールのユーザーインターフェイスのため)。
すべての現在のエンジンでサポートされています。
langIDL属性は、名前空間なしのlangコンテンツ属性を反映する必要があります。
translate 属性すべての現在のエンジンでサポートされています。
translate
属性は、要素の属性値とその Text
ノードの子がページのローカライズ時に翻訳されるか、または変更されずに残されるかを指定するために使用されます。この属性は 列挙型の属性であり、次のキーワードと状態を持ちます:
| キーワード | 状態 | 簡単な説明 |
|---|---|---|
yes
| yes | 翻訳モードを 翻訳可能 に設定します。 |
| (空の文字列) | ||
no
| no | 翻訳モードを翻訳不可に設定します。 |
この属性の 欠損値のデフォルト と 無効値のデフォルト はどちらも 継承 状態です。
すべての要素(非 HTML 要素も含む)は、翻訳モードを持ち、それは 翻訳可能 状態または 翻訳不可 状態のいずれかです。HTML要素の translate 属性が yes 状態にある場合、その要素の 翻訳モード は 翻訳可能 状態になります。それ以外の場合、要素の translate 属性が no 状態にある場合、その要素の 翻訳モード は 翻訳不可 状態になります。それ以外の場合、要素の translate 属性が 継承
状態にあるか、またはその要素がHTML要素でないため、translate
属性を持たない場合、いずれの場合もその要素の 翻訳モード
は、親要素が存在する場合、親要素と同じ状態になります。親要素が null の場合は 翻訳可能 状態になります。
要素が 翻訳可能 状態にある場合、その要素の 翻訳可能属性 とその Text
ノードの子の値は、ページがローカライズされたときに翻訳されます。
要素が 翻訳不可 状態にある場合、その要素の属性値とその Text
ノードの子の値は、ページがローカライズされたときにそのまま残されます。例えば、その要素に人名やプログラムの名前が含まれている場合です。
次の属性は 翻訳可能属性 です:
abbr 属性 (th 要素)
alt 属性 (area,
img, および input 要素)
content 属性 (meta 要素) で、name
属性が翻訳可能であることが知られているメタデータ名を指定する場合
download
属性 (a および area 要素)
label 属性 (optgroup, option, および track 要素)
lang 属性 (HTML要素); 翻訳時に使用される言語に合わせて「翻訳」する必要があります
placeholder 属性 (input および
textarea
要素)
srcdoc 属性 (iframe 要素);
解析され再帰的に処理される必要があります
style 属性 (HTML要素); 解析され再帰的に処理される必要があります(例:'content' プロパティの値について)
title 属性 (すべての HTML要素)
value 属性 (input 要素) で、type 属性が ボタン 状態または
リセットボタン 状態にある場合
他の仕様が、他の 翻訳可能属性
を定義する場合があります。例えば、ARIA では aria-label
属性が翻訳可能であると定義されます。
translate IDL
属性は、取得時に、要素の 翻訳モード が 翻訳可能 状態にある場合は true を返し、そうでない場合は
false を返す必要があります。設定時には、新しい値が true の場合はコンテンツ属性の値を "yes" に設定し、それ以外の場合はコンテンツ属性の値を "no"
に設定する必要があります。
この例では、ドキュメント内のすべてがページがローカライズされたときに翻訳されますが、サンプルのキーボード入力とサンプルのプログラム出力は例外です:
<!DOCTYPE HTML>
< html lang = en > <!-- default on the document element is translate=yes -->
< head >
< title > The Bee Game</ title > <!-- implied translate=yes inherited from ancestors -->
</ head >
< body >
< p > The Bee Game is a text adventure game in English.</ p >
< p > When the game launches, the first thing you should do is type
< kbd translate = no > eat honey</ kbd > . The game will respond with:</ p >
< pre >< samp translate = no > Yum yum! That was some good honey!</ samp ></ pre >
</ body >
</ html >
dir 属性すべての現在のエンジンでサポートされています。
dir 属性は 列挙属性 であり、次のキーワードと状態を持ちます:
| キーワード | 状態 | 簡潔な説明 |
|---|---|---|
ltr
| ltr | 要素の内容は左から右へのテキストとして明示的に方向が隔離されます。 |
rtl
| rtl | 要素の内容は右から左へのテキストとして明示的に方向が隔離されます。 |
auto
| auto | 要素の内容は明示的に方向が隔離されますが、その方向は要素の内容を使用してプログラムによって決定されます(以下に説明します)。 |
auto 状態で使用されるヒューリスティックは非常に粗いです (双方向アルゴリズムの段落レベルの決定に類似した方法で、最初の強い方向性を持つ文字のみを見ます)。著者は、テキストの方向が本当に不明で、サーバーサイドで適用できるより良いヒューリスティックがない場合にのみ、この値を最後の手段として使用するように勧められています。 [BIDI]
属性の 欠損値のデフォルト および 無効値のデフォルト はどちらも 未定義 状態です。
要素の 方向性 (HTML
要素に限らず、任意の要素)は、 'ltr' または 'rtl' のいずれかです。要素
element の 方向性 を計算するには、
element の dir 属性状態を基に判断します:
dir 属性は HTML 要素 のみ定義されているため、他の名前空間の要素には存在し得ません。したがって、他の名前空間の要素は常に 親方向性 を使用することになります。
自動方向性を持つフォーム関連要素 は次のとおりです:
自動方向性 を要素 element に対して計算するには:
element が 自動方向性を持つフォーム関連要素 である場合:
element が slot 要素で、その ルート が シャドウルート
であり、element の 割り当てられたノード
が空でない場合:
それぞれのノードchildに対して、elementの割り当てられたノードのうち:
childDirectionをnullに設定します。
childがTextノードである場合、childDirectionをchildのテキストノードの方向性に設定します。
その他の場合:
childDirectionをchildの含まれるテキストの自動方向性に設定します。ルートを除外できるかをtrueに設定して。
childDirectionがnullでない場合、childDirectionを返します。
nullを返します。
次にelementの含まれるテキストの自動方向性を返します。ルートを除外できるかをfalseに設定します。
含まれるテキストの自動方向性を、要素elementに対して計算するには:
それぞれのノードdescendantに対して、elementの子孫のうち、ツリー順に:
以下のいずれかが含まれる場合
以下のいずれかの場合
descendantがTextノードでない場合、続行します。
descendantのテキストノードの方向性をresultに設定します。
resultがnullでない場合、resultを返します。
nullを返します。
テキストノードの方向性を、Textノードtextに対して計算するには:
textのデータが双方向の文字タイプL、AL、またはRを持つコードポイントを含まない場合、nullを返します。 [BIDI]
textのデータの最初の双方向の文字タイプL、AL、またはRを持つコードポイントをcodePointに設定します。
codePointが双方向の文字タイプALまたはRを持つ場合、'rtl'を返します。
codePointが双方向の文字タイプLを持つ場合、'ltr'を返します。
親方向性を、要素elementに対して計算するには:
この属性は双方向アルゴリズムを含むレンダリング要件があります。
HTML要素の属性の方向性は、その属性のテキストが何らかの形でレンダリングに含まれるときに使用されますが、次のリストの最初の適切なステップに従って決定されます:
dir属性がauto状態である場合
属性の値に双方向の文字タイプL、AL、またはRの文字がある最初の文字(論理順序で)を見つけます。[BIDI]
そのような文字が見つかり、それが双方向の文字タイプALまたはRである場合、属性の方向性は 'rtl' です。
それ以外の場合、属性の方向性は 'ltr' です。
以下の属性は方向性対応の属性です:
abbr要素のth属性
alt属性がarea、img、およびinput要素
contentが、meta要素のname属性に人間が読むことを主に意図しているメタデータ名が指定されている場合
labelがoptgroup、option、およびtrack要素
placeholderがinputおよびtextarea要素
titleがすべてのHTML要素に指定されている
document.dir [ = value ]
設定可能であり、html要素のdir属性の値を「ltr」、「rtl」、または「auto」のいずれかに置き換えることができます。
html要素が存在しない場合、空の文字列を返し、新しい値は無視されます。
すべての現在のエンジンでサポートされています。
要素上のdir IDL属性は、その要素のdirコンテンツ属性を反映する必要があります。既知の値のみに制限されます。
すべての現在のエンジンでサポートされています。
IDL属性は、Documentオブジェクト上で、反映する必要があります。dirコンテンツ属性をhtml要素に設定します(存在する場合)。この要素が存在しない場合、この属性は空の文字列を返し、設定時には何もしません。dir
著者は、CSSを使用するのではなく、dir属性を使用してテキストの方向性を指定することを強くお勧めします。これにより、CSSがない場合でもドキュメントが正しくレンダリングされ続けるためです(例:
検索エンジンによって解釈される場合など)。
このマークアップフラグメントは、IMチャットの会話を示しています。
< p dir = auto class = "u1" >< b >< bdi > Student</ bdi > :</ b > How do you write "What's your name?" in Arabic?</ p >
< p dir = auto class = "u2" >< b >< bdi > Teacher</ bdi > :</ b > ما اسمك؟</ p >
< p dir = auto class = "u1" >< b >< bdi > Student</ bdi > :</ b > Thanks.</ p >
< p dir = auto class = "u2" >< b >< bdi > Teacher</ bdi > :</ b > That's written "شكرًا".</ p >
< p dir = auto class = "u2" >< b >< bdi > Teacher</ bdi > :</ b > Do you know how to write "Please"?</ p >
< p dir = auto class = "u1" >< b >< bdi > Student</ bdi > :</ b > "من فضلك", right?</ p >
適切なスタイルシートとp要素のデフォルトの配置スタイル(つまり段落の開始端にテキストを整列する)を与えると、レンダリング結果は次のようになる可能性があります。
前述のように、auto値は万能ではありません。この例の最後の段落はアラビア文字で始まるため、右から左のテキストとして誤解され、「right?」がアラビア文字の左に配置される結果になります。
style 属性すべての現在のエンジンでサポートされています。
すべてのHTML 要素には、styleコンテンツ属性が設定できます。これは、CSS Style
Attributesで定義されているスタイル属性です。[CSSATTR]
CSSをサポートするユーザーエージェントでは、属性が追加されるか値が変更された際に、その属性の値がスタイル属性の規則に従って解析される必要があります。[CSSATTR]
しかし、属性の要素のインライン動作がコンテンツセキュリティポリシーによってブロックされるべきかどうかアルゴリズムを属性の要素、「スタイル属性」、および属性の値で実行した際に「ブロック」と判断された場合、属性値で定義されたスタイルルールは要素には適用されません。[CSP]
ドキュメントが任意の要素にstyle属性を使用する場合、それらの属性が削除されても理解可能で使える状態でなければなりません。
特に、style属性を使用してコンテンツを非表示にしたり表示したり、またはドキュメントに他に含まれていない意味を伝えることは非準拠です(コンテンツを非表示にしたり表示したりするには、属性を使用してください)。
element.style
要素のstyle属性に対応するCSSStyleDeclarationオブジェクトを返します。
styleIDL属性は、CSS
Object Modelで定義されています。[CSSOM]
次の例では、色に言及している単語が、span要素とstyle属性を使用して、視覚的なメディアでその色を表示するようにマークアップされています。
< p > My sweat suit is < span style = "color: green; background:
transparent" > green</ span > and my eyes are < span style = "color: blue;
background: transparent" > blue</ span > .</ p >
data-*
属性
すべての現在のエンジンでサポートされています。
カスタムデータ属性は、名前が "data-" で始まり、
ハイフンの後に少なくとも1文字が続き、XML互換であり、
ASCIIの大文字アルファベットを含まない、名前空間に属さない属性です。
すべてのHTML要素において、HTML文書では、 属性名は自動的にASCII小文字化されるため、ASCII大文字の制限はそのような文書には影響しません。
カスタムデータ属性は、 ページやアプリケーションに固有のカスタムデータ、状態、注釈などを格納することを目的としています。これに適した他の属性や要素がない場合に使用されます。
これらの属性は、属性を使用するサイトの管理者に知られていないソフトウェアで使用することを意図していません。複数の独立したツールによって使用される汎用拡張機能には、この仕様を拡張して明示的に機能を提供するか、マイクロデータのような標準化された語彙を使用する技術を使用する必要があります。
たとえば、音楽に関するサイトが、アルバムのトラックを表すリスト項目に各トラックの長さを含むカスタムデータ属性を追加し、サイト自身がこの情報を使用してトラックの長さでリストをソートしたり、特定の長さのトラックをフィルタリングしたりできるようにすることが考えられます。
< ol >
< li data-length = "2m11s" > Beyond The Sea</ li >
...
</ ol >
ただし、汎用ソフトウェアがこのデータを使用して特定の長さのトラックを検索するのは不適切です。
これは、これらの属性はサイトのスクリプトによって使用されることを意図しており、公開可能なメタデータのための汎用的な拡張機構ではないからです。
同様に、ページ作成者が、使用する予定の翻訳ツール用の情報を提供するマークアップを書くこともできます。
< p > The third < span data-mytrans-de = "Anspruch" > claim</ span > covers the case of < span
translate = "no" > HTML</ span > markup.</ p >
この例では、「data-mytrans-de」属性は、「claim」をドイツ語に翻訳する際にMyTrans製品が使用する特定のテキストを提供します。ただし、標準のtranslate属性は、「HTML」がすべての言語で変更されないように指示しています。標準の属性が利用できる場合、カスタムデータ属性を使用する必要はありません。
この例では、PaymentRequestの機能検出の結果をカスタムデータ属性に保存し、チェックアウトページを異なるスタイルで表示するためにCSSで使用することができます。
< script >
if ( 'PaymentRequest' in window) {
document. documentElement. dataset. hasPaymentRequest = '' ;
}
</ script >
ここで、data-has-payment-request属性は、ブール属性として効果的に使用されています。属性の存在を確認するだけで十分です。しかし、著者が望む場合、後で機能の限定された機能を示す値を格納することもできます。
すべてのHTML要素には、任意の数のカスタムデータ属性を指定し、任意の値を持たせることができます。
著者は、これらの拡張が無視され、関連するCSSが削除されてもページが引き続き使用可能であるように慎重に設計する必要があります。
ユーザーエージェントは、これらの属性や値から実装動作を派生させてはなりません。ユーザーエージェントを対象とした仕様は、これらの属性に意味のある値を定義してはなりません。
JavaScriptライブラリは、カスタムデータ属性を使用することができます。それらは、使用されるページの一部と見なされるからです。多くの著者が再利用するライブラリの著者は、競合のリスクを減らすために、属性名に名前を含めることを推奨します。また、可能であれば、ライブラリ著者は、属性名に使用する正確な名前をカスタマイズできるAPIを提供することをお勧めします。そうすれば、同じ名前を知らずに選んだライブラリを同じページで使用したり、互換性のない複数のバージョンを同じページで使用することができます。
たとえば、「DoQuery」というライブラリは、data-doquery-rangeのような属性名を使用し、「jJo」というライブラリは、data-jjo-rangeのような属性名を使用することができます。また、jJoライブラリは、使用するプレフィックスを設定するAPIを提供することができます(例:J.setDataPrefix('j2')、これにより、属性名がdata-j2-rangeになります)。
element.dataset
すべての現在のエンジンでサポートされています。
すべての現在のエンジンでサポートされています。
要素のdata-*属性のためのDOMStringMapオブジェクトを返します。
ハイフンで区切られた名前はキャメルケースに変換されます。例えば、data-foo-bar=""はelement.dataset.fooBarとなります。
datasetIDL属性は、要素上のすべてのdata-*属性への便利なアクセサを提供します。取得時に、datasetIDL属性は、この要素に関連付けられたDOMStringMapを返さなければなりません。
DOMStringMapインターフェイスは、dataset属性のために使用されます。各DOMStringMapには、関連付けられた要素があります。
[Exposed =Window ,
LegacyOverrideBuiltIns ]
interface DOMStringMap {
getter DOMString (DOMString name );
[CEReactions ] setter undefined (DOMString name , DOMString value );
[CEReactions ] deleter undefined (DOMString name );
};
DOMStringMapの名前と値のペアを取得するには、次のアルゴリズムを実行します。
list を名前と値のペアの空のリストにします。
DOMStringMapの関連付けられた要素上の、最初の5文字が
"data-" で始まり、残りの文字にASCIIの大文字アルファベットが含まれていない各コンテンツ属性について、それらの属性が要素の属性リストに表示される順序で、属性名の最初の5文字を削除した名前と属性の値を持つ名前と値のペアをlistに追加します。
listの各名前に対して、その名前にU+002Dハイフンマイナス文字(-)が含まれており、ASCIIの小文字アルファベットが続いている場合、U+002Dハイフンマイナス文字(-)を削除し、その後に続く文字を同じ文字で置き換え、ASCII大文字に変換します。
listを返します。
DOMStringMapオブジェクトのサポートされているプロパティ名は、その瞬間に名前と値のペアを取得して返される各ペアの名前であり、その瞬間に返される順序で返されます。
名前付きプロパティの値を決定するには、nameと、リストにある名前がDOMStringMapで取得された名前と値のペアのリストの名前要素であり、値要素を返します。
新しい名前付きプロパティの値を設定する、または既存の名前付きプロパティの値を設定するには、プロパティ名nameと新しい値valueを指定して、次の手順を実行します。
nameがU+002Dハイフンマイナス文字(-)を含み、その後にASCIIの小文字アルファベットが続く場合、"SyntaxError"をスローします。DOMException。
name内の各ASCII大文字に対して、文字の前にU+002Dハイフンマイナス文字(-)を挿入し、その文字を同じ文字で置き換え、ASCII小文字に変換します。
nameの先頭にdata-文字列を挿入します。
nameがXMLName生成規則と一致しない場合、"InvalidCharacterError"をスローします。DOMException。
属性値を設定します、DOMStringMapのnameとvalueを使用して、関連付けられた要素を使用します。
既存の名前付きプロパティを削除するnameのために、次の手順を実行します。
name内の各ASCII大文字に対して、文字の前にU+002Dハイフンマイナス文字(-)を挿入し、その文字を同じ文字で置き換え、ASCII小文字に変換します。
nameの先頭にdata-文字列を挿入します。
名前によって属性を削除します、nameとDOMStringMapのnameと関連付けられた要素を使用します。
このアルゴリズムは、[WEBIDL]によって、名前と値のペアを取得するために以前のアルゴリズムによって与えられた名前に対してのみ呼び出されます。
例えば、ウェブページが宇宙船を表す要素を持ちたい場合(例えば、ゲームの一部として)、それはクラス属性と共にdata-*属性を使用する必要があります。
< div class = "spaceship" data-ship-id = "92432"
data-weapons = "laser 2" data-shields = "50%"
data- x = "30" data-y = "10" data-z = "90" >
< button class = "fire"
onclick = "spaceships[this.parentNode.dataset.shipId].fire()" >
Fire
</ button >
</ div >
ハイフンで区切られた属性名がAPIでキャメルケースになることに注意してください。
次のフラグメントと同様の構造を持つ要素を考えてみましょう。
< img class = "tower" id = "tower5" data- x = "12" data-y = "5"
data-ai = "robotarget" data-hp = "46" data-ability = "flames" src = "towers/rocket.png" alt = "Rocket Tower" >
...スプラッシュダメージを処理する関数splashDamage()があり、その最初の引数が処理する要素であると考えられます。
function splashDamage( node, x, y, damage) {
if ( node. classList. contains( 'tower' ) && // 'class' 属性をチェックします
node. dataset. x == x && // 'data-x' 属性を読み取ります
node. dataset. y == y) { // 'data-y' 属性を読み取ります
var hp = parseInt( node. dataset. hp); // 'data-hp' 属性を読み取ります
hp = hp - damage;
if ( hp < 0 ) {
hp = 0 ;
node. dataset. ai = 'dead' ; // 'data-ai' 属性を設定します
delete node. dataset. ability; // 'data-ability' 属性を削除します
}
node. dataset. hp = hp; // 'data-hp' 属性を設定します
}
}
innerText および outerText プロパティすべての現行エンジンでサポートされています。
element.innerText [ = value ]
要素の「レンダリングされた」テキストコンテンツを返します。
指定された値で要素の子を置き換えることができますが、改行はbr要素に変換されます。
element.outerText [ = value ]
要素の「レンダリングされた」テキストコンテンツを返します。
指定された値で要素を置き換えることができますが、改行はbr要素に変換されます。
テキスト取得手順は、HTMLElement elementに対して次のように行います:
もしelementがレンダリングされていないか、ユーザーエージェントが非CSSユーザーエージェントの場合、elementの子孫テキストコンテンツを返します。
このステップは驚くべき結果を生むことがあります。たとえば、innerTextゲッターがレンダリングされていない要素で呼び出された場合、そのテキストコンテンツが返されますが、レンダリングされている要素でアクセスされた場合、レンダリングされていないすべての子要素のテキストコンテンツは無視されます。
resultsを新しい空のリストとします。
elementの各子ノードnodeに対して:
currentを、レンダリングされたテキスト収集手順をnodeで実行した結果として得られるリストとします。resultsの各項目は文字列または正の整数(必須の改行数)となります。
直感的には、必須の改行数の項目は、そのポイントに一定数の改行が出現することを意味しますが、これらは隣接する必須の改行数の項目によって誘導される改行とともに折り畳まれることがあります。これはCSSのマージン折り畳みと似ています。
current内の各項目itemについて、itemをresultsに追加します。
削除します。resultsから空の文字列となる項目を削除します。
削除します。resultsの先頭または末尾にある連続した必須の改行数項目のランを削除します。
置換します。残りの連続する必須の改行数項目のランを、それぞれの必須の改行数項目の値の最大値と同じ数のU+000A LFコードポイントを含む文字列に置き換えます。
resultsの文字列項目を連結して返します。
すべての現在のエンジンでサポートされています。
innerTextと
outerText
のゲッターステップは、テキスト取得手順をthisで実行した結果を返すことです。
レンダリングされたテキスト収集手順は、ノード nodeに対して次のように行います:
itemsを、nodeの各子ノードに対してレンダリングされたテキスト収集手順を実行し、その結果をリストとして連結したものにします。
もしnodeの計算値が'visibility'が'visible'でない場合、itemsを返します。
もしnodeがレンダリングされていない場合、itemsを返します。このステップの目的のために、次の要素は、計算値が'display'が'none'でない場合に記載されているように動作しなければなりません:
select要素は、非置換インラインCSSボックスを持ち、その子ボックスはoptgroupおよびoption要素の子ノードのみを含みます。
optgroup要素は、非置換ブロックレベルCSSボックスを持ち、その子ボックスはoption要素の子ノードのみを含みます。
itemsは'display:contents'のために空でない可能性があります。
もしnodeがテキストノードである場合、nodeが生成する各CSSテキストボックスに対して、内容の順番で、そのボックスのテキストをCSSの'white-space'処理ルールと'text-transform'ルールを適用した後のテキストを計算し、itemsを得られた文字列のリストに設定し、itemsを返します。
CSSの'white-space'処理ルールは若干修正されます。行の終わりの折り畳み可能なスペースは常に折り畳まれますが、行がブロックの最後の行であるか、br要素で終了する場合にのみ削除されます。ソフトハイフンは保持されるべきです。
[CSSTEXT]
もしnodeの計算値が'display'が'table-cell'であり、nodeのCSSボックスが、それを囲む'table-row'ボックスの最後の'table-cell'ボックスでない場合、追加します。itemsにU+0009 TABコードポイントを含む文字列を追加します。
もしnodeの計算値が'display'が'table-row'であり、nodeのCSSボックスが最も近い祖先'table'ボックスの最後の'table-row'ボックスでない場合、追加します。itemsにU+000A LFコードポイントを含む文字列を追加します。
もしnodeの使用値が'display'がブロックレベルまたは'テーブルキャプション'である場合、追加します。itemsの先頭と末尾に1(必須の改行数)を追加します。[CSSDISPLAY]
フロートや絶対配置された要素はこのカテゴリに該当します。
itemsを返します。
注意、ほとんどの置換要素の子ノード(例:textarea、
input、
video — ただし
buttonは除く)は、
厳密にはCSSによってレンダリングされず、このアルゴリズムの目的にはCSSボックスを持ちません。
このアルゴリズムはレンジに対して一般化して動作するようにすることができます。これにより、Selectionの文字列化に使用できる基盤となり、おそらくレンジで直接公開することができます。詳細はBugzilla bug 10583をご覧ください。
内部テキスト設定手順は、HTMLElement elementと文字列valueが与えられた場合に以下を実行します:
fragmentを、elementのノードドキュメントが与えられたvalueのためのレンダリングされたテキストフラグメントにします。
すべてを置き換えるでelement内のfragmentを使用します。
innerTextの
セッターステップは、内部テキスト設定手順を実行することです。
outerTextの
セッターステップは以下の通りです:
もしthisの親がnullである場合、"NoModificationAllowedError" DOMExceptionをスローします。
fragmentを、与えられた値のためにレンダリングされたテキストフラグメントにします。
もしfragmentに子ノードがない場合、新しいテキストノードを追加します。データが空の文字列であり、ノードドキュメントがthisのノードドキュメントである新しいノードをfragmentに追加します。
もしnextがnullでなく、nextの前の兄弟ノードがテキストノードである場合、nextの次のテキストノードとマージします。
もしpreviousがテキストノードである場合、previousを用いて次のテキストノードとマージします。
レンダリングされたテキストフラグメントは、documentが与えられたドキュメントに対して、文字列inputのために次の手順を実行します:
fragmentを、新しいドキュメントフラグメントにします。そのノードドキュメントはdocumentです。
positionをinputの位置変数に設定し、初期値はinputの先頭を指します。
textを空の文字列にします。
positionがinputの終わりを過ぎていない間:
コードポイントのシーケンスを収集するを行います。U+000A LFまたはU+000D CRではないコードポイントをinputから収集し、positionに設定します。
もしtextが空の文字列でない場合、新しいテキストノードをfragmentに追加します。そのデータはtextであり、ノードドキュメントはdocumentです。
positionがinputの終わりを過ぎていない間、およびpositionにあるコードポイントがU+000A LFまたはU+000D CRである間:
fragmentを返します。
次のテキストノードとマージは、テキストノードnodeが与えられた場合に以下を実行します:
nextをnodeの次の兄弟ノードにします。
もしnextがテキストノードでない場合、終了します。
データを置き換えます。nodeを使用し、nodeのデータの長さ、0、およびnextのデータを置き換えます。
もしnextの親がnullでない場合、削除します。nextを親ノードから削除します。
親ノードのチェックは、前のステップで変更イベントが発生した可能性があるため必要です。
テキストコンテンツがHTML要素に含まれるテキストノード内や、自由形式のテキストを許可するHTML要素の属性内には、U+202AからU+202EおよびU+2066からU+2069の範囲にある文字(双方向アルゴリズム書式設定文字)が含まれることがあります。[BIDI]
著者は、双方向アルゴリズム書式設定文字を手動で管理するのではなく、dir属性、bdo要素、およびbdi要素を使用することが推奨されます。双方向アルゴリズム書式設定文字はCSSと相性が悪いです。
ユーザーエージェントは、文書や文書の一部をレンダリングする際に文字の適切な順序を決定するために、Unicode双方向アルゴリズムを実装しなければなりません。[BIDI]
HTMLをUnicode双方向アルゴリズムにマッピングする方法は3つのいずれかでなければなりません。ユーザーエージェントはCSSを実装しなければならず、特にCSSの'unicode-bidi'、'direction'、および'content'プロパティを実装しなければならず、そのユーザーエージェントスタイルシートにこの仕様のレンダリングセクションに記載されているこれらのプロパティを使用したルールが含まれている必要があります。あるいは、ユーザーエージェントは、上述のプロパティのみを実装し、文書に指定されたスタイルシートがそれらを上書きしないようにしつつ、ユーザーエージェントスタイルシートがすべての前述のルールを含んでいるかのように振る舞う必要があります。または、ユーザーエージェントは同等のセマンティクスを持つ他のスタイリング言語を実装しなければなりません。[CSSGC]
次の要素と属性には、レンダリングセクションで定義されている要件があり、このセクションの要件により、すべてのユーザーエージェントに対して(推奨されるデフォルトのレンダリングをサポートするものだけでなく)要件が課されます:
ユーザーエージェントがHTML要素HTML要素でアクセシビリティAPIのセマンティクスを実装するための要件は、HTML Accessibility API Mappingsに定義されています。また、カスタム要素elementに対して、デフォルトのARIAロールセマンティクスは次のように決定されます:[HTMLAAM]
mapをelementの内部コンテンツ属性マップに設定します。
もしmap["role"]が存在する場合、それを返します。
ロールを返しません。
同様に、カスタム要素elementに対して、ARIAステートおよびプロパティセマンティクスのデフォルトは、stateOrPropertyという名前のステートまたはプロパティに対して、次のように決定されます:
もしelementのアタッチされた内部がnullでない場合:
もしelementのアタッチされた内部の関連するstateOrProperty要素を取得するが存在する場合、それを実行した結果を返します。
もしelementのアタッチされた内部の関連するstateOrProperty要素を取得するが存在する場合、それを実行した結果を返します。
もしelementの内部コンテンツ属性マップ[stateOrProperty]が存在する場合、それを返します。
stateOrPropertyのデフォルト値を返します。
ここで言及されている「デフォルトのセマンティクス」は、ARIAで「ネイティブ」、「暗黙的」、または「ホスト言語セマンティクス」とも呼ばれることがあります。[ARIA]
これらの定義の1つの含意は、デフォルトのセマンティクスが時間とともに変化する可能性があるということです。これにより、カスタム要素は組み込み要素と同様の表現力を持つことができます。たとえば、a要素のデフォルトのARIAロールセマンティクスが、href属性の追加や削除によってどのように変わるかと比較できます。
この動作の例については、カスタム要素セクションを参照してください。
ARIA roleおよびaria-*属性の使用をチェックするための適合チェッカーの要件は、ARIA in
HTMLに定義されています。[ARIAHTML]
html 要素すべての現在のエンジンでサポートされています。
すべての現在のエンジンでサポートされています。
head 要素の後に
body 要素が続く。
html 要素の開始タグは、html 要素内の最初の要素がコメントでない場合、省略できます。
html 要素の終了タグは、html 要素の直後にコメントがない場合、省略できます。
[Exposed =Window ]
インターフェース HTMLHtmlElement : HTMLElement {
[HTMLConstructor ] コンストラクタ ();
// 非推奨メンバーも含む
};
著者は、ルートhtml要素にlang属性を指定して文書の言語を設定することが推奨されています。これにより、音声合成ツールが使用する発音を判断し、翻訳ツールが適用するルールを判断するのに役立ちます。
以下の例のhtml
要素は、文書の言語が英語であることを宣言しています。
<!DOCTYPE html>
< html lang = "en" >
< head >
< title > Swapping Songs</ title >
</ head >
< body >
< h1 > Swapping Songs</ h1 >
< p > Tonight I swapped some of the songs I wrote with some friends, who gave me some of the songs they wrote. I love sharing my music.</ p >
</ body >
</ html >
head
要素すべての現行エンジンでサポートされています。
すべての現行エンジンでサポートされています。
html要素の最初の要素として。
iframe
srcdocドキュメントである場合、または上位プロトコルからタイトル情報が提供されている場合:
メタデータ内容の0個以上の要素。その中にtitle要素は1つのみ、base要素は1つのみ。
title要素は1つのみ、base要素は1つのみ。
head要素の開始タグは、要素が空の場合、またはhead要素内の最初のものが要素の場合、省略可能です。
head要素の終了タグは、head要素が直後にASCII ホワイトスペースまたはコメントがない場合、省略可能です。
[Exposed =Window ]
interface HTMLHeadElement : HTMLElement {
[HTMLConstructor ] constructor ();
};
head要素内のメタデータの集合は、大きい場合も小さい場合もあります。以下は非常に短いものの例です。
<!doctype html>
< html lang = en >
< head >
< title > A document with a short head</ title >
</ head >
< body >
...
以下は、より長いものの例です。
<!DOCTYPE HTML>
< HTML LANG = "EN" >
< HEAD >
< META CHARSET = "UTF-8" >
< BASE HREF = "https://www.example.com/" >
< TITLE > An application with a long head</ TITLE >
< LINK REL = "STYLESHEET" HREF = "default.css" >
< LINK REL = "STYLESHEET ALTERNATE" HREF = "big.css" TITLE = "Big Text" >
< SCRIPT SRC = "support.js" ></ SCRIPT >
< META NAME = "APPLICATION-NAME" CONTENT = "Long headed application" >
</ HEAD >
< BODY >
...
title
要素はほとんどの状況で必須の子要素ですが、
上位プロトコルがタイトル情報を提供する場合、たとえばHTMLがメール作成形式として使用される場合のメールの件名で、
title要素は省略できます。
title
要素すべての現在のエンジンでサポートされています。
すべての現在のエンジンでサポートされています。
title要素を含まないhead要素内で。
[Exposed =Window ]
interface HTMLTitleElement : HTMLElement {
[HTMLConstructor ] constructor ();
[CEReactions ] attribute DOMString text ;
};
title要素は、ドキュメントのタイトルまたは名前を表します。
著者は、ドキュメントが文脈を外れて使用された場合でも識別できるタイトルを使用するべきです。例えば、ユーザーの履歴やブックマーク、検索結果などで使用される場合です。ドキュメントのタイトルは、文脈を外れても独立して存在する必要がない最初の見出しとは異なることが多いです。
ドキュメントにはtitle要素が1つしか存在してはいけません。
ドキュメントDocumentにタイトルが必要ない場合は、title要素が不要である可能性があります。要素が必要かどうかについては、head要素のコンテンツモデルを参照してください。
title.text [ = value ]
要素の子テキストコンテンツを返します。
設定可能であり、指定された値で要素の子を置き換えます。
text
属性のゲッターは、このtitle要素の子テキストコンテンツを返す必要があります。
text属性のセッターは、すべての文字列を置き換え、このtitle要素内に指定された値を適用する必要があります。
ここでは、適切なタイトルの例と、その同じページで使用されるトップレベルの見出しとの対比を示します。
< title > Introduction to The Mating Rituals of Bees</ title >
...
< h1 > Introduction</ h1 >
< p > This companion guide to the highly successful
< cite > Introduction to Medieval Bee-Keeping</ cite > book is...
次のページは同じサイトの一部かもしれません。タイトルが主題を明確に記述しているのに対して、最初の見出しは文脈を理解している読者を前提としているため、ダンスがサルサなのかワルツなのかを疑問に思うことはありません:
< title > Dances used during bee mating rituals</ title >
...
< h1 > The Dances</ h1 >
ドキュメントのタイトルとして使用する文字列は、document.titleIDL属性によって与えられます。
ユーザーエージェントは、ユーザーインターフェイスでドキュメントを参照する際に、ドキュメントのタイトルを使用する必要があります。title要素の内容がこのように使用される場合、そのtitle要素の方向性を使用して、ユーザーインターフェイス内でドキュメントのタイトルの方向性を設定する必要があります。
base
要素すべての現在のエンジンでサポートされています。
すべての現在のエンジンでサポートされています。
base要素を含まないhead要素内で。
href — ドキュメントの基本 URL
target — デフォルトのナビゲーション可能なハイパーリンクのナビゲーションおよびフォームの送信
[Exposed =Window ]
interface HTMLBaseElement : HTMLElement {
[HTMLConstructor ] constructor ();
[CEReactions ] attribute USVString href ;
[CEReactions ] attribute DOMString target ;
};
base要素は、ドキュメントの基本 URLを指定して、URLの解析を行うためのものであり、ナビゲーション可能なデフォルトの名前を指定してハイパーリンクをたどるためのものです。この要素は、この情報以外のコンテンツを表すものではありません。
ドキュメントにはbase要素が1つしか存在してはいけません。
base要素には、href属性、target属性、またはその両方が必要です。
href属性が指定されている場合、その内容は有効な URLを含んでいる必要があります。
base要素にhref属性がある場合、それはツリー内の他のすべての要素(html要素を除く)の前に配置されなければなりません(manifest属性はbase要素に影響されません)。
複数のbase要素がhref属性を持つ場合、最初の要素以外は無視されます。
target属性が指定されている場合、それには有効なナビゲーション可能なターゲット名またはキーワードが含まれている必要があります。これは、ナビゲーション可能な要素がハイパーリンクおよびフォームがナビゲーションを行う際のデフォルトとして使用されることを指定します。
base要素がtarget属性を持つ場合、それはツリー内のハイパーリンクを表す要素の前に配置されなければなりません。
複数のbase要素がtarget属性を持つ場合、最初の要素以外は無視されます。
要素のターゲットを取得するには、a、area、またはform要素elementおよびオプションの文字列またはnull(デフォルトはnull)targetを指定して、次の手順を実行します。
もしtargetがnullであれば:
もしtargetがnullでなく、ASCII
タブまたは改行文字を含み、かつU+003C(<)を含んでいる場合、targetを"_blank"に設定します。
targetを返します。
base要素が最初のbase要素であり、hrefコンテンツ属性を持つ要素である場合、凍結された基本 URLを持ちます。次のいずれかの状況が発生したときに、凍結された基本 URLを即座に設定しなければなりません。
凍結された基本 URL を設定するには、要素elementに対して次の手順を実行します:
elementのノードドキュメントをdocumentとします。
urlRecordを、elementのhrefコンテンツ属性の値をdocumentのフォールバック基本
URLおよびdocumentの文字エンコーディングで解析した結果とします。(したがって、base要素は自身に影響を受けません。)
次のいずれかが真である場合:
urlRecordが失敗である場合;
urlRecordのスキームが「data」または「javascript」である場合;
urlRecordおよびdocumentに対してドキュメントに対して base
が許可されているかを実行し、「Blocked」が返される場合、elementの凍結された基本 URLをdocumentのフォールバック基本 URLに設定し、終了します。
elementの凍結された基本 URLをurlRecordに設定します。
hrefIDL属性は、取得時に次のアルゴリズムを実行した結果を返す必要があります:
elementのノードドキュメントをdocumentとします。
urlを、この要素のhref属性の値(存在する場合)とし、存在しない場合は空文字列とします。
urlRecordを、documentのフォールバック基本 URLおよびdocumentの文字エンコーディングでurlを解析した結果とします。(したがって、base要素は他のbase要素や自身の影響を受けません。)
urlRecordが失敗した場合、urlを返します。
urlRecordのシリアル化を返します。
hrefIDL属性は、設定時に、指定された新しい値でhrefコンテンツ属性を設定する必要があります。
targetIDL属性は、同じ名前のコンテンツ属性を反映する必要があります。
この例では、base要素を使用して、ドキュメントの基本 URLを設定しています:
<!DOCTYPE html>
< html lang = "en" >
< head >
< title > This is an example for the < base> element</ title >
< base href = "https://www.example.com/news/index.html" >
</ head >
< body >
< p > Visit the < a href = "archives.html" > archives</ a > .</ p >
</ body >
</ html >
上記の例のリンクは、"https://www.example.com/news/archives.html" へのリンクになります。
link要素すべての現在のエンジンでサポートされています。
すべての現在のエンジンでサポートされています。
noscript要素の中で、かつhead要素の子として。href — ハイパーリンクのアドレスcrossorigin —
要素がクロスオリジンリクエストをどのように処理するかrel — ハイパーリンクを含む文書とリンク先のリソースとの関係media — 適用可能なメディアintegrity —
サブリソースインテグリティチェックに使用されるインテグリティメタデータ [SRI]
hreflang — リンクされたリソースの言語
type — 参照されるリソースの種類のヒントreferrerpolicy
— 要素によって開始されるフェッチに対するリファラーポリシーsizes — アイコンのサイズ(rel="icon"の場合)imagesrcset —
異なる状況(例:高解像度ディスプレイ、小型モニターなど)で使用する画像(rel="preload"の場合)imagesizes —
異なるページレイアウトに対応する画像のサイズ(rel="preload"の場合)as — プリロードリクエストの潜在的な宛先(rel="preload"およびrel="modulepreload"の場合)
blocking — 要素が潜在的にレンダーブロックかどうか
color —
サイトのアイコンをカスタマイズするときに使用する色(rel="mask-icon"の場合)
disabled — リンクが無効かどうか
fetchpriority
— 要素によって開始されるフェッチに対する優先度を設定titleがあります: リンクのタイトル; CSSスタイルシートセット名[Exposed =Window ]
interface HTMLLinkElement : HTMLElement {
[HTMLConstructor ] constructor ();
[CEReactions ] attribute USVString href ;
[CEReactions ] attribute DOMString ? crossOrigin ;
[CEReactions ] attribute DOMString rel ;
[CEReactions ] attribute DOMString as ;
[SameObject , PutForwards =value ] readonly attribute DOMTokenList relList ;
[CEReactions ] attribute DOMString media ;
[CEReactions ] attribute DOMString integrity ;
[CEReactions ] attribute DOMString hreflang ;
[CEReactions ] attribute DOMString type ;
[SameObject , PutForwards =value ] readonly attribute DOMTokenList sizes ;
[CEReactions ] attribute USVString imageSrcset ;
[CEReactions ] attribute DOMString imageSizes ;
[CEReactions ] attribute DOMString referrerPolicy ;
[SameObject , PutForwards =value ] readonly attribute DOMTokenList blocking ;
[CEReactions ] attribute boolean disabled ;
[CEReactions ] attribute DOMString fetchPriority ;
// 古いメンバーもあります
};
HTMLLinkElement には LinkStyle ;
link要素は、著者がドキュメントを他のリソースにリンクさせることを可能にします。
リンクのアドレスはhref属性によって指定されます。href属性が存在する場合、その値は有効な空でないURL(周囲にスペースがある可能性あり)でなければなりません。hrefまたはimagesrcsetのいずれか、または両方の属性が存在している必要があります。
hrefおよびimagesrcset属性が両方とも存在しない場合、この要素はリンクを定義しません。
示されるリンクの種類(関係性)はrel属性の値によって決定されます。もし存在するならば、その値はユニークな空白で区切られたトークンの順不同セットでなければなりません。許可されるキーワードとその意味は後のセクションで定義されています。rel属性が存在しない、またはキーワードがない、または使用されたキーワードがこの仕様で定義されている許可されたキーワードに該当しない場合、この要素はリンクを作成しません。
relのサポートされるトークンは、HTMLリンクタイプで定義されており、link要素に許可されているもの、処理モデルに影響を与えるもの、そしてユーザーエージェントでサポートされているものです。可能なサポートされるトークンは以下の通りです:alternate、dns-prefetch、expect、icon、manifest、modulepreload、next、pingback、preconnect、prefetch、preload、search、およびstylesheetです。relのサポートされるトークンは、ユーザーエージェントが処理モデルを実装しているこのリストのトークンのみを含める必要があります。
理論的には、canonicalキーワードの処理モデルをサポートするユーザーエージェントが存在する可能性がありますが、それはJavaScriptを実行する検索エンジンである場合に限られます。しかし、実際にはそれは非常にまれです。したがって、ほとんどの場合、canonicalはrelのサポートされるトークンに含めるべきではありません。
link要素は、rel属性またはitemprop属性のいずれか一方、しかし両方ではなく、を持つ必要があります。
link要素がitemprop属性を持っているか、またはrel属性にbody-okとして指定されているキーワードのみが含まれている場合、その要素は本文に許可されるとされます。これは、その要素がフレージングコンテンツが期待される場所で使用できることを意味します。
もしrel属性が使用されている場合、この要素はページのbody内でのみ使用できる場合があります。itemprop属性と一緒に使用される場合、この要素はhead要素内およびページのbody内の両方で使用できますが、これはマイクロデータモデルの制約を受けます。
link要素を使用して、2つのカテゴリのリンクを作成できます:
外部リソースへのリンクとハイパーリンクです。リンクタイプのセクションでは、特定のリンクタイプが外部リソースかハイパーリンクかを定義しています。1つのlink要素は、複数のリンクを作成できます(そのうちのいくつかは外部リソースリンクで、他はいくつかはハイパーリンクであるかもしれません)。どのリンクがどれだけ作成されるかは、rel属性に指定されたキーワードによって決まります。ユーザーエージェントは、リンクを要素単位ではなく、リンク単位で処理する必要があります。
1つのlink要素で作成される各リンクは、個別に処理されます。例えば、link要素が2つあり、どちらもrel="stylesheet"である場合、それぞれが別個の外部リソースと見なされ、各リソースはそれぞれの属性によって独立して影響を受けます。同様に、1つのlink要素がrel属性にnext stylesheetの値を持つ場合、それはnextキーワードによって1つのハイパーリンクとstylesheetキーワードによって1つの外部リソースリンクを作成し、他の属性(例えばmediaやtitle)によって異なる影響を受けます。
例えば、次のlink要素は、同じページへの2つのハイパーリンクを作成します:
< link rel = "author license" href = "/about" >
この要素によって作成される2つのリンクは、1つが現在のページの著者に関する情報を持っているという意味を持ち、もう1つが現在のページが提供されているライセンスに関する情報を持っているという意味を持っています。
ハイパーリンクは、link要素とそのrel属性で作成され、ドキュメント全体に適用されます。これは、rel属性を持つaやarea要素とは対照的であり、これらの要素はドキュメント内でリンクが配置された場所によってリンクのコンテキストが決まります。
aおよびarea要素によって作成されたリンクとは異なり、ハイパーリンクは、link要素によって作成されても、デフォルトではドキュメントの一部として表示されません。これらのリンクは主にセマンティック情報を提供し、その情報はページやページのコンテンツを消費する他のソフトウェアによって使用される可能性があります。さらに、ユーザーエージェントは、そのようなハイパーリンクをたどるための独自のUIを提供することができます。
外部リソースへのリンクの正確な動作は、関連するリンクタイプで定義された正確な関係に依存します。
crossorigin属性は、CORS設定属性です。これは、外部リソースリンクでの使用を意図しています。
media属性は、リソースが適用されるメディアを指定します。値は有効なメディアクエリリストでなければなりません。
すべての現在のエンジンでサポートされています。
integrity
属性は、この要素が担当するリクエストの
整合性メタデータ
を表します。値はテキストです。この属性は、link
要素で、rel 属性に
stylesheet、
preload、
または modulepreload
キーワードを含む場合にのみ指定する必要があります。 [SRI]
hreflang 属性は、
link 要素にあり、
hreflang
属性と同じ意味を持ちます。
type 属性は、リンクされたリソースの
MIME タイプ
を指定します。これは純粋に参考のためのものです。値は 有効な MIME
タイプ文字列
でなければなりません。
外部リソースリンク の場合、
type 属性は、ユーザーエージェントがサポートしていないリソースを
フェッチしないようにするためのヒントとして使用されます。
referrerpolicy属性は、リファラーポリシー属性です。これは外部リソースリンクでの使用を意図しており、リンクされたリソースをフェッチおよび処理する際に使用されるリファラーポリシーを設定するのに役立ちます。[REFERRERPOLICY]
title 属性はリンクのタイトルを指定します。
1つの例外を除いて、これは純粋に参考のためのものです。その例外は、ドキュメントツリー内 にある
スタイルシートリンクの場合で、この場合、title 属性は、
CSS スタイルシートセット を定義します。
title 属性は、
link 要素のグローバル属性である
title 属性とは異なります。
他の多くの要素においては、タイトルのないリンクは親要素のタイトルを継承しません。それは単にタイトルがないだけです。
imagesrcset属性が存在する可能性があり、これはsrcset属性です。
imagesrcset属性とhref属性(幅記述子が使用されていない場合)を一緒に使用すると、画像ソースがソースセットに追加されます。
もしimagesrcset属性が存在し、かつ画像候補文字列が幅記述子を使用している場合、imagesizes属性も存在する必要があり、これはサイズ属性です。imagesizes属性はソースサイズをソースセットに提供します。
imagesrcset属性とimagesizes属性は、link要素にのみ指定する必要があります。この要素には、rel属性にpreloadキーワードが指定されていること、およびas属性が"image"状態にあることが条件となります。
これらの属性を使用すると、後で対応するsrcsetおよびsizes属性を持つimg要素で使用される適切なリソースをプリロードできます。
< link rel = "preload" as = "image" imagesrcset = "wolf_400px.jpg 400w, wolf_800px.jpg 800w, wolf_1600px.jpg 1600w" imagesizes = "50vw" >
この例では、href属性を省略しています。これは、imagesrcsetをサポートしないブラウザに対してのみ関連性があり、その場合、誤った画像がプリロードされる可能性があるためです。
imagesrcset属性は、media属性と組み合わせて使用することができ、アートディレクション用のリソースを適切にプリロードできます。
< link rel = "preload" as = "image" imagesrcset = "dog-cropped-1x.jpg, dog-cropped-2x.jpg 2x" media = "(max-width: 800px)" >
sizes属性は、視覚メディア用のアイコンのサイズを指定します。値が存在する場合、それは単なるアドバイスです。ユーザーエージェントは、複数のアイコンが利用可能な場合にどのアイコンを使用するかを決定するために値を使用する可能性があります。指定されている場合、属性の値は一意のスペースで区切られたトークンの順序のないセットであり、ASCII大文字と小文字を区別しないである必要があります。各値は、文字列"any"とASCII大文字と小文字を区別しない一致を持つか、または有効な非負整数2つで構成され、それらはU+0030DIGIT ZERO
(0)文字を先頭に持たず、1つのU+0078 LATIN SMALL LETTER XまたはU+0058 LATIN CAPITAL LETTER X文字で区切られます。この属性は、link要素にのみ指定される必要があります。この要素にはrel属性が指定されており、アイコンキーワードまたはapple-touch-iconキーワードを指定している必要があります。
apple-touch-iconキーワードは、リンクタイプの事前定義セットへの拡張として登録されていますが、ユーザーエージェントはこれをサポートする必要はありません。
as属性は、href属性で指定されたリソースのプリロードリクエストの潜在的な宛先を指定します。これは列挙された属性です。各潜在的な宛先は、この属性のキーワードであり、同名の状態にマッピングされます。この属性は、link要素に指定する必要があり、rel属性にpreloadキーワードが含まれている必要があります。link要素には、rel属性にmodulepreloadキーワードが含まれている場合に指定することができます。その場合、スクリプトに類似した宛先の値を持たなければなりません。他のlink要素では、指定する必要はありません。
as属性の使用方法に関する処理モデルは、個々のリンクタイプのリンクされたリソースのフェッチおよび処理アルゴリズムに記載されています。
この属性には、欠落値のデフォルトまたは無効値のデフォルトがありません。したがって、属性の無効な値や欠落した値は、どの状態にもマップされません。これは処理モデルで考慮されています。preloadリンクの場合、どちらの条件もエラーです。modulepreloadリンクの場合、欠落値は"script"として扱われます。
blocking属性は、ブロッキング属性です。この属性は、stylesheetおよびexpectリンクタイプで使用され、これらのキーワードを含むrel属性を持つリンク要素にのみ指定される必要があります。
color属性はmask-iconリンクタイプで使用されます。この属性は、link要素にのみ指定される必要があります。この要素にはrel属性が含まれ、mask-iconキーワードを含んでいる必要があります。値は、CSSの<color>プロダクションと一致する文字列である必要があり、サイトをピン留めした際にユーザーが表示するアイコンの表示をカスタマイズするための推奨される色を定義します。
この仕様には、color属性に関するユーザーエージェントの要件は含まれていません。
mask-iconキーワードは、リンクタイプの事前定義セットへの拡張として登録されていますが、ユーザーエージェントはこれをサポートする必要はありません。
link要素には、明示的に有効化されているかどうかを示すブール値が関連付けられています。これは初期状態ではfalseです。
disabled属性はブール属性であり、stylesheetリンクタイプで使用されます。この属性は、link要素にのみ指定される必要があります。この要素にはrel属性が含まれ、stylesheetキーワードを含んでいる必要があります。
いつでもdisabled属性が削除されると、link要素の明示的に有効化された属性がtrueに設定されます。
disabled属性を動的に削除すると、例えばdocument.querySelector("link").removeAttribute("disabled")を使用することで、スタイルシートがフェッチされて適用されます。
< link disabled rel = "alternate stylesheet" href = "css/pooh" >
fetchpriority属性はフェッチ優先度属性であり、外部リソースリンクで使用することを目的としています。ここでは、リンクされたリソースをフェッチして処理する際に使用される優先順位を設定します。
すべての現在のエンジンでサポートされています。
IDL属性href、hreflang、integrity、media、rel、sizes、type、blocking、およびdisabledは、それぞれ同名のコンテンツ属性を反映する必要があります。
color属性には反映されるIDL属性がありませんが、これは後で追加される可能性があります。
すべての現在のエンジンでサポートされています。
asIDL属性は、asコンテンツ属性を反映し、既知の値のみに限定されます。
crossOriginIDL属性は、crossoriginコンテンツ属性を反映し、既知の値のみに限定されます。
HTMLLinkElement/referrerPolicy
すべての現在のエンジンでサポートされています。
referrerPolicyIDL属性は、referrerpolicyコンテンツ属性を反映し、既知の値のみに限定されます。
fetchPriorityIDL属性は、fetchpriorityコンテンツ属性を反映し、既知の値のみに限定されます。
imageSrcsetIDL属性は、imagesrcsetコンテンツ属性を反映しなければなりません。
imageSizesIDL属性は、imagesizesコンテンツ属性を反映しなければなりません。
すべての現在のエンジンでサポートされています。
relListIDL属性は、relコンテンツ属性を反映しなければなりません。
relList属性は、機能検出に使用できます。supports()メソッドを呼び出して、どのリンクタイプがサポートされているかを確認することができます。
media 属性の処理リンクが ハイパーリンク である場合、media
属性は純粋に助言的なものであり、当該文書がどのメディア向けに設計されているかを説明します。
しかし、リンクが 外部リソースリンク
である場合、media
属性は強制的です。ユーザーエージェントは、media 属性の値が環境と一致する場合、他の関連する条件が適用されるときに外部リソースを適用し、そうでない場合は適用してはなりません。
media
属性が省略された場合のデフォルトは「all」であり、デフォルトではリンクはすべてのメディアに適用されることを意味します。
外部リソースにはその適用範囲を制限するさらなる制約が定義されている場合があります。たとえば、CSSスタイルシートには@mediaブロックが含まれていることがあります。この仕様は、そのような追加の制約や要件を上書きしません。
type 属性の処理 type
属性が存在する場合、ユーザーエージェントはリソースが指定されたタイプであると仮定しなければなりません(たとえそれが有効なMIMEタイプ文字列ではない場合、例えば空文字列であっても)。属性が省略されているが、外部リソースリンク
タイプにデフォルトのタイプが定義されている場合、ユーザーエージェントはリソースがそのタイプであると仮定しなければなりません。ユーザーエージェントが指定されたリンクの関係に対して指定されたMIMEタイプをサポートしていない場合、ユーザーエージェントはリンクされたリソースを取得および処理してはならず、ユーザーエージェントが指定されたリンク関係に対して指定されたMIMEタイプをサポートしている場合、ユーザーエージェントは外部リソースリンクの特定のタイプに指定された適切なタイミングでリンクされたリソースを取得および処理する必要があります。属性が省略されていて、外部リソースリンクのタイプにデフォルトのタイプが定義されていないが、ユーザーエージェントがタイプが既知でサポートされている場合にリンクされたリソースを取得および処理する場合、ユーザーエージェントはリンクされたリソースがサポートされると仮定して取得および処理するべきです。
ユーザーエージェントは、 type
属性を権威あるものと見なしてはなりません。リソースを取得した際、ユーザーエージェントは type
属性を使用してその実際のタイプを決定してはなりません。リソースを適用するかどうかを決定するために使用されるのは、上記の仮定されたタイプではなく、実際のタイプです。
もし 外部リソースリンク タイプがリソースの Content-Type メタデータ を処理するためのルールを定義している場合、そのルールが適用されます。それ以外の場合、リソースが画像であると予想される場合、ユーザーエージェントは画像スニッフィングルールを適用し、リソースの Content-Type メタデータ から決定されたタイプを公式タイプとして適用し、得られた計算されたタイプを実際のタイプであるかのように使用することができます。これらの条件のいずれかが適用されない場合、またはユーザーエージェントが画像スニッフィングルールを適用しない場合、ユーザーエージェントはリソースのContent-Type メタデータを使用してリソースのタイプを決定する必要があります。タイプメタデータが存在しないが、外部リソースリンク タイプにデフォルトのタイプが定義されている場合、ユーザーエージェントはリソースがそのタイプであると仮定しなければなりません。
stylesheetリンクタイプは、リソースの
Content-Type メタデータ
を処理するためのルールを定義しています。
ユーザーエージェントがリソースのタイプを確立したら、ユーザーエージェントはサポートされているタイプであり、他の関連条件が適用される場合にリソースを適用し、そうでない場合はリソースを無視する必要があります。
ドキュメントに以下のようにラベル付けされたスタイルシートリンクが含まれている場合:
< link rel = "stylesheet" href = "A" type = "text/plain" >
< link rel = "stylesheet" href = "B" type = "text/css" >
< link rel = "stylesheet" href = "C" >
...その場合、CSSスタイルシートのみをサポートする準拠したユーザーエージェントは、BファイルとCファイルを取得し、Aファイルをスキップします(text/plainがCSSスタイルシートのMIMEタイプではないため)。
BファイルとCファイルについては、次にサーバーによって返された実際のタイプを確認します。それらが text/cssとして送信された場合、スタイルが適用されますが、それが
text/plain、またはその他のタイプとしてラベル付けされている場合は適用されません。
もし2つのファイルのうち1つが Content-Type メタデータ
なしで返されたり、「null」のような構文的に誤ったタイプで返されたりした場合、stylesheetリンクのデフォルトタイプが適用されます。このデフォルトタイプが
text/cssであるため、スタイルシートは適用されます。
link
要素からリソースを取得して処理するすべての外部リソースリンクは、リンクされたリソースの取得と処理
アルゴリズムを持ち、これはlink
要素elを引数とします。また、リンクされたリソースの取得準備ステップがあり、これはlink
要素elとリクエストrequestを引数とします。個別のリンクタイプが独自のリンクされたリソースの取得と処理アルゴリズムを提供することがありますが、特に明記されていない限り、デフォルトの取得と処理アルゴリズムを使用します。
同様に、個別のリンクタイプが独自のリンクされたリソースの取得準備ステップを提供することがありますが、特に明記されていない限り、これらのステップは常にtrueを返します。
デフォルトのリンクされたリソースの取得と処理は、link
要素elを引数として以下の手順で行います:
optionsをリンク要素からオプションを作成する結果として取得します。
requestをリンクリクエストを作成する結果として取得します。
requestがnullである場合、リターンします。
requestの同期フラグを設定します。
リンクされたリソースの取得準備ステップを実行し、elとrequestを渡します。結果がfalseの場合、リターンします。
requestのイニシエータータイプを、elのrel属性にキーワードstylesheetが含まれている場合は「css」、それ以外の場合は「link」に設定します。
リクエストをフェッチし、レスポンス処理ボディを消費するを次の手順で設定し、 レスポンス responseとnull、失敗、またはバイトシーケンス bodyBytesを指定します:
successをtrueに設定します。
次のいずれかがtrueである場合:
その場合、successをfalseに設定します。
CSSのパースエラーやPNGのデコードエラーなど、コンテンツ固有のエラーはsuccessに影響を与えません。
それ以外の場合、リンクリソースのクリティカルサブリソースの読み込みが完了するまで待機します。
リンクタイプのクリティカルサブリソースを定義する仕様(例:CSS)は、これらのサブリソースがどのようにフェッチされ処理されるかを記述することが期待されています。しかし、これは現在明示的ではないため、この仕様ではリンクリソースのクリティカルサブリソースがフェッチされ処理されるのを待つことを記述し、これが正しく行われることを期待しています。
リンクされたリソースを処理するステップを、el、success、response、およびbodyBytesを指定して実行します。
リンクリクエストを作成するためには、リンク処理オプション optionsを使用します:
もしoptionsのdestinationがnullである場合、nullを返します。
urlをURLのエンコードとパースの結果として取得し、optionsのhrefを基にoptionsの基本URLに対して相対的に行います。
基本URLをドキュメントや環境の代わりに渡すことはissue #9715によって追跡されています。
urlが失敗した場合、nullを返します。
requestをポテンシャルCORSリクエストを作成する結果として取得し、url、optionsのdestination、およびoptionsのcrossoriginを指定します。
requestのインテグリティメタデータをoptionsのインテグリティに設定します。
requestの暗号学的ナンスメタデータをoptionsの暗号学的ナンスメタデータに設定します。
requestを返します。
ユーザーエージェントは、必要に応じてのみこれらのリソースをフェッチして処理することを選択するかもしれません。すべての外部リソースを事前に積極的にフェッチする代わりに、適用されていないものはフェッチしません。
リンクされたリソースの取得と処理アルゴリズムに類似して、すべての外部リソースリンクは、リンクされたリソースを処理するアルゴリズムを持っており、これにはlink要素el、ブール値success、レスポンスresponse、およびバイトシーケンスbodyBytesを引数とします。個別のリンクタイプが独自のリンクされたリソースを処理するアルゴリズムを提供することがありますが、特に明記されていない限り、そのアルゴリズムは何も行いません。
特定のrelキーワードに対して別段の指定がない限り、要素はその要素のロードイベントを遅延させる必要があります。この遅延は要素のノードドキュメントまで適用され、すべての試みがリンクされたリソースの取得と処理とそのクリティカルサブリソースの完了まで行われます。(ユーザーエージェントがまだフェッチおよび処理を試みていないリソース、例えばリソースが必要になるまで待機しているものはロードイベントを遅延しません。)
Link`
ヘッダーの処理外部リソースリンクとなりうるすべてのリンクタイプは、リンク処理オプションを受け取る、リンクヘッダーを処理するアルゴリズムを定義しています。このアルゴリズムは、HTTPレスポンスヘッダーに`Link`
ヘッダーとして表示された場合に、それらがどのように反応するかを定義します。
ほとんどのリンクタイプでは、このアルゴリズムは何もしません。要約表は、リンクタイプが定義されたリンクヘッダーを処理する手順を持っているかどうかをすばやく確認するのに役立ちます。
link")
Document
Documentを受け取るアルゴリズム
自動)
リンク処理オプションにはベースURLとhrefがありますが、これは、URLがオプションのソースセットの結果である可能性があるためです。
リンク要素からリンクオプションを作成するには、link要素elを指定します:
documentをelのノードドキュメントとします。
optionsを次のリンク処理オプションとして新しく作成します。
as属性の状態を翻訳した結果。
crossoriginコンテンツ属性の状態
referrerpolicyコンテンツ属性の状態
fetchpriorityコンテンツ属性の状態
もしelがintegrity属性を持っている場合、optionsのintegrityをelのintegrityコンテンツ属性の値に設定します。
アサート: optionsのhrefが空文字列でないか、またはoptionsのソースセットがnullでないか。
link要素がhrefやimagesrcsetを持たない場合、リンクを表しません。
optionsを返します。
ヘッダーからリンクを抽出するには、ヘッダーリスト headersを指定します:
linksを新しいリストとします。
rawLinkHeadersを取得、デコード、分割する結果を取得し、responseのlinkを
ヘッダーリストから取得します。
各 linkHeaderに対して、rawLinkHeadersの内容を次のように処理します:
linksを返します。
リンクヘッダーを処理するには、Document doc、レスポンス
response、および"pre-media"または"media"フェーズを指定します:
各 linkObjectに対して、linksの内容を次のように処理します:
relをlinkObject["relation_type"]として取得します。
attribsをlinkObject["target_attributes"]として取得します。
expectedPhaseを"media"として取得します。もしsrcset、
"imagesrcset",
またはmediaがattribsに存在する場合、それ以外の場合は"pre-media"を取得します。
もしexpectedPhaseがphaseでない場合、処理を続けます。
optionsを次のリンク処理オプションとして新しく作成します。
target_uri"]
解析されたヘッダー属性からリンクオプションを適用します。attribsを指定してoptionsに適用します。
もしattribs["imagesrcset"]が存在し、attribs["imagesizes"]が存在する場合、optionsのソースセットをlinkObject["target_uri"],
attribs["imagesrcset"],attribs["imagesizes"],およびnullを指定してソースセットを作成します。
リンクヘッダーを処理する手順をrelに対して実行し、optionsを指定します。
解析されたヘッダー属性からリンクオプションを適用するには、リンク処理オプション optionsをattribsを指定して適用します:
もしattribs["as"]が存在する場合、optionsの宛先をattribs["as"]を翻訳した結果に設定します。
もしattribs["crossorigin"]が存在し、ASCII大文字小文字を区別しない比較により、CORS設定属性キーワードのいずれかに一致する場合、optionsのクロスオリジンをそのキーワードに対応するCORS設定属性状態に設定します。
もしattribs["integrity"]が存在する場合、optionsのintegrityをattribs["integrity"]に設定します。
もしattribs["referrerpolicy"]が存在し、ASCII大文字小文字を区別しない比較により、リファラーポリシーのいずれかに一致する場合、optionsのリファラーポリシーをそのリファラーポリシーに設定します。
もしattribs["nonce"]が存在する場合、optionsのノンスをattribs["nonce"]に設定します。
もしattribs["fetchpriority"]が存在し、ASCII大文字小文字を区別しない比較により、フェッチ優先度属性キーワードのいずれかに一致する場合、optionsのフェッチの優先度をそのフェッチ優先度属性キーワードに設定します。
早期ヒントは、ナビゲーションリクエストがサーバーによって完全に処理され、レスポンスコードが提供される前に、ドキュメントによって使用される可能性のあるリソースを推測的にロードするなど、ユーザーエージェントがいくつかの操作を実行できるようにします。サーバーは、最終的なレスポンスを提供する前に、103ステータスコードを使用してレスポンスを提供することで早期ヒントを示すことができます。[RFC8297]
互換性の理由から、早期ヒントは通常HTTP/2以降で提供されますが、可読性のために、以下ではHTTP/1.1スタイルの表記を使用しています。
たとえば、次のレスポンスシーケンスが与えられた場合:
103 Early Hint Link: </image.png>; rel=preload; as=image
200 OK Content-Type: text/html <!DOCTYPE html> ... <img src="/image.png">
画像はHTMLコンテンツが到着する前にロードを開始します。
ナビゲーション中に提供される最初の早期ヒントレスポンスのみが処理され、クロスオリジンリダイレクトが続く場合は破棄されます。
`Link`
ヘッダーに加えて、103レスポンスにコンテンツセキュリティポリシーヘッダーが含まれている可能性があり、早期ヒントを処理する際に適用されます。
たとえば、次のレスポンスシーケンスが与えられた場合:
103 Early Hint Content-Security-Policy: style-src: self; Link: </style.css>; rel=preload; as=style
103 Early Hint Link: </image.png>; rel=preload; as=image
302 Redirect Location: /alternate.html
200 OK Content-Security-Policy: style-src: none; Link: </font.ttf>; rel=preload; as=font
フォントとスタイルはロードされ、画像は破棄されます。最終的なリダイレクトチェーンで最初の早期ヒントレスポンスのみが尊重されます。リクエストがスタイルをフェッチする前に遅れて送信されたコンテンツセキュリティポリシーヘッダーは、スタイルがドキュメントにアクセスできないようにします。
早期ヒントヘッダーを処理するには、レスポンス responseと環境 reservedEnvironmentを指定します:
早期ヒント`Link`
ヘッダーは、最終的なレスポンスからの`Link`
ヘッダー、次にlink要素の前に常に処理されます。これは、早期および最終的な`Link`ヘッダーの内容を、Documentのhead要素にそれぞれ順番に追加することと同等です。
earlyPolicyContainerをresponseとreservedEnvironmentを指定してフェッチレスポンスからポリシーコンテナを作成した結果とします。
これにより、早期ヒントレスポンスにコンテンツセキュリティポリシーを含めることができ、早期ヒントリクエストをフェッチするときに適用されます。
earlyHintsを空のリストとします。
各 linkObjectに対して、linksの内容を次のように処理します:
早期ヒントリンクヘッダーを受信した瞬間に、earlyRequestのフェッチを開始します。Documentが作成される前に戻ってきた場合、そのレスポンスをearlyResponseとして設定し、Documentが作成されると、それをコミットします(link要素であるかのようにプリロードされたリソースのマップで利用可能にします)。Documentが先に作成された場合、レスポンスが利用可能になった時点でそれをコミットします。
relをlinkObject["relation_type"]として取得します。
optionsを次のリンク処理オプションとして新しく作成します。
attribsをlinkObject["target_attributes"]として取得します。
as、
crossorigin、
integrity、
およびtype属性は、早期ヒント処理の一部として処理されます。他の属性、特にblocking、
imagesrcset、
imagesizes、
およびmediaは、Documentが作成された後にのみ適用されます。
解析されたヘッダー属性からリンクオプションを適用します。attribsを指定してoptionsに適用します。
optionsを基にrelに対してリンクヘッダーを処理する手順を実行する。
optionsをearlyHintsに追加する。
次のサブステップをDocument docに対して実行します:
各 optionsをearlyHintsに含めます:
もしoptionsのドキュメント準備完了時がnullである場合、optionsのドキュメントをdocに設定します。
そうでない場合、optionsのドキュメント準備完了時を呼び出してdocを渡します。
link要素を使用して作成されたハイパーリンクをユーザーが辿る手段の提供
インタラクティブなユーザーエージェントは、ユーザーにlink要素を使用して作成されたハイパーリンクを辿る手段をユーザーインターフェース内のどこかに提供することができます。このハイパーリンクを辿るアルゴリズムの呼び出しでは、userInvolvement引数を"ブラウザーUI"に設定する必要があります。具体的なインターフェースはこの仕様では定義されていませんが、以下の情報を含むことが考えられます(要素の属性から取得し、以下で定義されているように、いずれかの形式で、可能であれば簡略化された形で)、ドキュメント内の各link要素で作成された各ハイパーリンクについて:
rel属性による)
title属性による)
href属性による)
hreflang属性による)
media属性による)
ユーザーエージェントは、リソースの種類(type属性による)など、他の情報も含めることができます。
meta要素すべての現在のエンジンでサポートされています。
すべての現在のエンジンでサポートされています。
itemprop属性が存在する場合:フローコンテンツ。
itemprop属性が存在する場合:フレージングコンテンツ。
charset属性が存在する場合、または要素のhttp-equiv属性がエンコーディング宣言状態にある場合:head要素内で使用します。
http-equiv属性が存在するが、エンコーディング宣言状態にない場合:head要素内で使用します。
http-equiv属性が存在するが、エンコーディング宣言状態にない場合:noscript要素内で、かつhead要素の子要素として使用します。
name属性が存在する場合:メタデータコンテンツが期待される場所で使用します。
itemprop属性が存在する場合:メタデータコンテンツが期待される場所で使用します。
itemprop属性が存在する場合:フレージングコンテンツが期待される場所で使用します。
name — メタデータ名
http-equiv —
プラグマ指示
content — 要素の値
charset — 文字エンコーディング宣言
media — 適用メディア
[Exposed =Window ]
interface HTMLMetaElement : HTMLElement {
[HTMLConstructor ] constructor ();
[CEReactions ] attribute DOMString name ;
[CEReactions ] attribute DOMString httpEquiv ;
[CEReactions ] attribute DOMString content ;
[CEReactions ] attribute DOMString media ;
// 非推奨メンバーもあります
};
meta要素は、title、base、link、style、およびscript要素を使用して表現できないさまざまな種類のメタデータを表します。
meta要素は、name属性を使用してドキュメントレベルのメタデータを表すことができ、http-equiv属性を使用してプラグマ指示を表し、HTMLドキュメントが文字列形式にシリアル化される場合(例:
ネットワーク経由での送信やディスクに保存する場合)には、charset属性を使用して文字エンコーディング宣言を行います。
正確には、name、http-equiv、charset、およびitemprop属性のうちの1つだけが指定されている必要があります。
name、http-equiv、またはitempropのいずれかが指定されている場合、content属性も指定する必要があります。そうでない場合は、省略する必要があります。
charset属性は、ドキュメントで使用される文字エンコーディングを指定します。これは文字エンコーディング宣言です。この属性が存在する場合、その値は"utf-8"という文字列に対してASCII大文字小文字を区別しない一致でなければなりません。
charset属性は、XMLドキュメントでは効果がありませんが、XMLドキュメント間の移行を容易にするために許可されています。
meta要素には、ドキュメントごとにcharset属性を持つ要素が複数存在してはなりません。
content属性は、要素がこれらの目的で使用される場合に、ドキュメントのメタデータまたはプラグマ指示の値を示します。許可される値は、次のセクションで説明されているように、正確なコンテキストに依存します。
meta要素にname属性がある場合、それはドキュメントメタデータを設定します。ドキュメントメタデータは、名前と値のペアの形式で表現され、name属性が名前を示し、同じ要素のcontent属性が値を示します。名前は、設定されているメタデータの側面を指定します。有効な名前とその値の意味は、次のセクションで説明されています。meta要素にcontent属性がない場合、メタデータの名前と値のペアの値の部分は空文字列になります。
media属性は、メタデータが適用されるメディアを示します。その値は有効なメディアクエリリストでなければなりません。nameがtheme-colorでない限り、media属性は処理モデルには影響せず、著者によって使用されるべきではありません。
name、content、およびmediaIDL属性は、同じ名前の対応するコンテンツ属性を反映する必要があります。IDL属性httpEquivは、コンテンツ属性http-equivを反映する必要があります。
すべての現在のエンジンでサポートされています。
この仕様では、name
属性を持つ meta
要素のためにいくつかの名前が定義されています。
名前は大文字と小文字を区別せず、ASCII 大文字と小文字を区別しない 方法で比較される必要があります。
application-name
値は、そのページが表す Web アプリケーションの名前を示す、短い自由形式の文字列でなければなりません。ページが Web アプリケーションでない場合、application-name
メタデータ名を使用してはなりません。Web アプリケーションの名前の翻訳は、lang 属性を使用して各言語を指定することができます。
文書内で、同じ 言語 を持ち、name 属性の値が
ASCII 大文字と小文字を区別しない 方式で
application-name
と一致する meta
要素は、文書ごとに 1 つしか存在してはなりません。
ユーザーエージェントは、UI でページの title
よりもアプリケーション名を優先して使用することができます。なぜなら、タイトルには、特定の時点でのページのステータスに関連するステータスメッセージなどが含まれている可能性があるからです。
指定された言語の順序付きリストが与えられた場合(例:イギリス英語、アメリカ英語、英語)、ユーザーエージェントは次の手順を実行する必要があります:
languages を言語のリストとします。
default language を、言語とし、Document の
ドキュメント要素の言語に設定します。
その言語が未知でない場合に限ります。
もし default language があり、languages に含まれている言語とは異なる場合、それを languages に追加します。
winning language を、languages の中で最初に、次の条件を満たす meta
要素が存在する言語とします。その name
属性の値が、application-name
と
ASCII 大文字と小文字を区別しない
方式で一致し、その言語が 言語 と一致するものです。
もしどの言語にもそのような meta
要素が存在しない場合、リターンします。与えられたアプリケーション名は存在しません。
最初の meta
要素の
content
属性の値を返します。
その要素は Document 内で ツリー順 で最初に見つかるもので、
name 属性の値が
ASCII 大文字と小文字を区別しない
方式で一致し、その言語が winning language であるものです。
このアルゴリズムは、例えばブックマークにラベルを付ける際に、ブラウザがページ名を必要とする場合に使用されます。ユーザーがアルゴリズムに提供する言語は、ユーザーの好みの言語となります。
author
値は、ページの著者の名前を示す自由形式の文字列でなければなりません。
description
値はページを説明する自由形式の文字列でなければなりません。この値は、ページのディレクトリ(例:検索エンジン)で使用するのに適している必要があります。
meta
要素が name 属性値と
ASCII 大文字小文字の区別なく
description
と一致する文書ごとに、1つしか存在してはなりません。
generator
値は、文書の生成に使用されたソフトウェアパッケージの1つを識別する自由形式の文字列でなければなりません。この値は、例えば、ユーザーがテキストエディタでマークアップを書いたページのように、ソフトウェアによって生成されていないページには使用してはなりません。
"Frontweaver"というツールが、ページの head
要素内に出力するものを示します。このツールがページの生成に使用されたことを識別するためのものです:
< meta name = generator content = "Frontweaver 8.2" >
keywords
値は、ページに関連するキーワードのコンマ区切りトークンのセットでなければなりません。
このページは、イギリスの高速道路の書体に関するものであり、ユーザーがページを検索する際に使用する可能性のあるいくつかのキーワードを指定するために
meta
要素を使用しています:
<!DOCTYPE HTML>
< html lang = "en-GB" >
< head >
< title > Typefaces on UK motorways</ title >
< meta name = "keywords" content = "british,type face,font,fonts,highway,highways" >
</ head >
< body >
...
多くの検索エンジンは、この機能が歴史的に信頼性に欠け、ユーザーに役立たない方法で検索エンジンの結果をスパムする手段として誤用されてきたため、このようなキーワードを考慮しないことがあります。
ユーザーエージェントが、ページに適用可能なキーワードのリストを取得するには、次の手順を実行する必要があります:
keywords を空のリストにします。
meta
要素のそれぞれに対して、name 属性と
content
属性を持ち、name
属性の値が ASCII 大文字小文字の区別なく
keywords
と一致する場合:
要素の content 属性の値をコンマで分割します。
結果のトークンがあれば、それを keywords に追加します。
keywords から重複を削除します。
keywords を返します。これは、ページに適用可能として著者が指定したキーワードのリストです。
ユーザーエージェントは、値の信頼性に対する十分な確信がない場合、この情報を使用すべきではありません。
例えば、コンテンツ管理システムが、システム内のページのキーワード情報を使用して、サイト固有の検索エンジンのインデックスを作成するのは合理的ですが、大規模なコンテンツアグリゲーターがこの情報を使用すると、一部のユーザーが不適切なキーワードを使用してランキングメカニズムを操作しようとする可能性が高くなります。
referrer
この値は、文書 のデフォルトの リファラーポリシー を定義する リファラーポリシー でなければなりません。 [REFERRERPOLICY]
任意の meta 要素
element が
文書に 挿入された 場合、
またはその name または
content
属性が変更された場合、ユーザーエージェントは次のアルゴリズムを実行する必要があります:
element が 文書ツリー内 にない場合、戻ります。
element に、値が "referrer" と
ASCII 大文字小文字を区別しない 一致する
name
属性がない場合、戻ります。
element に content
属性がない場合、
またはその属性の値が空の文字列である場合、戻ります。
以下の表の最初の列にある値のいずれかで value がある場合、 value を2列目に示す値に設定します:
| レガシー値 | リファラーポリシー |
|---|---|
never
|
no-referrer
|
default
| デフォルトのリファラーポリシー |
always
|
unsafe-url
|
origin-when-crossorigin
|
origin-when-cross-origin
|
value が リファラーポリシー の1つである場合、 element の ノード文書 の ポリシーコンテナ の リファラーポリシー を policy に設定します。
歴史的な理由から、他の標準メタデータ名とは異なり、referrer
の処理モデルは、要素の削除に応答せず、ツリー順
を使用しません。この状態の中で最も最近挿入された、または最も最近変更された meta
要素のみが影響を与えます。
theme-color
この値は、CSS の <color> プロダクションと一致する文字列でなければならず、 ユーザーエージェントがページまたは周辺のユーザーインターフェイスの表示をカスタマイズするために使用する推奨される色を定義します。たとえば、ブラウザーは、指定された値を使用してページのタイトルバーをカラー表示したり、タブバーやタスクスイッチャーでハイライトとして使用することがあります。
HTML ドキュメント内では、media
属性の値は、meta
要素のすべての中で一意でなければなりません。また、name
属性の値は、theme-color
と
ASCII 大文字小文字を区別しない 一致でなければなりません。
この標準自体は、「WHATWG グリーン」をテーマカラーとして使用しています:
<!DOCTYPE HTML>
< title > HTML Standard</ title >
< meta name = "theme-color" content = "#3c790a" >
...
media
属性は、提供された色が使用されるべきコンテキストを説明するために使用される場合があります。
この標準のテーマカラーとして「WHATWG グリーン」をダークモードでのみ使用したい場合は、prefers-color-scheme メディア機能を使用できます:
<!DOCTYPE HTML>
< title > HTML Standard</ title >
< meta name = "theme-color" content = "#3c790a" media = "(prefers-color-scheme: dark)" >
...
ページのテーマカラーを取得するには、ユーザーエージェントは次の手順を実行する必要があります:
candidate elements を、以下の基準を満たすすべての meta
要素のリストとします。
順序は ツリー順 です。
その要素が 文書ツリーに含まれている こと。
その要素が name
属性を持ち、その値が theme-color
と
ASCII 大文字小文字を区別しない 一致していること。
その要素が content
属性を持っていること。
candidate elements の各 element について:
何も返しません(ページにテーマカラーがない場合)。
任意の meta
要素が 文書に挿入される
または 文書から削除される 場合、
または既存の meta
要素の name、
content、
または media
属性が変更される、または環境が変化して、いずれかの meta
要素の media
属性の値が環境と一致するか、
一致しなくなる場合は、ユーザーエージェントは上記のアルゴリズムを再実行し、その結果を影響を受ける UI に適用する必要があります。
UI でテーマカラーを使用する際、ユーザーエージェントは、該当する UI に適した形でテーマカラーを調整することがあります。たとえば、ユーザーエージェントがテーマカラーを背景色として使用し、その上に白いテキストを表示することを意図している場合、十分なコントラストを確保するために、その部分の UI でテーマカラーのより暗いバージョンを使用することがあります。
color-scheme
ユーザーエージェントがページの背景をすぐに希望する配色でレンダリングできるようにするため(ページ内のすべての CSS の読み込みを待つのではなく)、meta
要素で 'color-scheme' 値を指定できます。
この値は、CSS の 'color-scheme' プロパティの値の構文に一致する文字列でなければなりません。 これにより、ページがサポートする配色 が決定されます。
ドキュメント内では、meta
要素に
name 属性値が
ASCII 大文字小文字を区別しない 一致で
color-scheme に
設定された要素が 1 つ以上あってはなりません。
次の宣言は、ページが暗い背景色と明るい前景色を含む配色に対応していることを示しています:
< meta name = "color-scheme" content = "dark" >
ページがサポートする配色を取得するには、ユーザーエージェントは次の手順を実行する必要があります:
candidate elements を、以下の基準を満たすすべての meta
要素のリストとします。
順序は ツリー順 です。
その要素が 文書ツリーに含まれている こと。
その要素が name
属性を持ち、その値が color-scheme
と
ASCII 大文字小文字を区別しない 一致していること。
その要素が content
属性を持っていること。
candidate elements の各 element について:
content
属性の値を与えて、コンポーネント値のリストを解析する結果を
parsed とします。
null を返します。
任意の meta
要素が 文書に挿入される
または 文書から削除される 場合、
または既存の meta
要素の name または
content
属性が変更された場合、ユーザーエージェントは上記のアルゴリズムを再実行する必要があります。
これらのルールは一致する要素が見つかるまで次々に要素を確認するため、著者はレガシーユーザーエージェントのフォールバックに対応する複数の値を提供できます。 プロパティに対する CSS のフォールバックの仕組みとは逆に、複数の meta 要素は、レガシー値が新しい値の後に配置される必要があります。
誰でも独自のメタデータ名の事前定義セットに対する拡張を作成して使用することができます。このような拡張を登録する必要はありません。
ただし、次のいずれかの場合には、新しいメタデータ名を作成すべきではありません:
その名前がURLである場合、またはその付随するcontent
属性の値がURLである場合。このような場合には、新しいメタデータ名を作成するのではなく、リンクタイプの事前定義セットに対する拡張として登録することが推奨されます。
その名前がユーザーエージェントで処理要件が予想されるものである場合、その場合は標準化されるべきです。
また、新しいメタデータ名を作成して使用する前に、WHATWG Wiki MetaExtensions ページを参照することが推奨されます。 これは、既に使用されているメタデータ名を選択するのを避け、既に使用されているメタデータ名の目的を重複させることを避け、新しい標準化された名前が 選択した名前と衝突するのを避けるためです。[WHATWGWIKI]
誰でもいつでも WHATWG Wiki MetaExtensions ページを編集してメタデータ名を追加することができます。 新しいメタデータ名は、次の情報で指定することができます:
実際に定義される名前です。この名前は、他の定義済みの名前と混同されないようにする必要があります(例: 大文字小文字のみが異なる場合など)。
メタデータ名の意味とその値が要求される形式についての簡潔で非標準的な説明です。
まったく同じ処理要件を持つ他の名前のリストです。著者は、定義された同義語の名前を使用すべきではありません(これはレガシーコンテンツのサポートのためにのみ意図されています)。 誰でも、実際には使用されていない同義語を削除することができます。レガシーコンテンツとの互換性のために同義語として処理する必要がある名前のみがこの方法で登録されます。
次のいずれかです:
メタデータ名が既存の値と重複していると判明した場合、それは削除され、既存の値の同義語としてリストされるべきです。
メタデータ名が「提案」状態で1か月以上使用されずに追加された場合、または仕様されていない場合、それは WHATWG Wiki MetaExtensions ページから削除される可能性があります。
メタデータ名が「提案」状態で追加され、既存の値と重複していると判明した場合、それは削除され、既存の値の同義語としてリストされるべきです。 メタデータ名が「提案」状態で追加され、害があると判明した場合、それは「中止」状態に変更されるべきです。
誰でもいつでもステータスを変更できますが、上記の定義に従ってのみ行うべきです。
http-equiv属性が
meta要素に指定されている場合、
その要素はプラグマ指令となります。
http-equiv属性は、
以下のキーワードと状態を持つ列挙型属性です:
| キーワード | 適合性 | 状態 | 簡潔な説明 |
|---|---|---|---|
content-language
| No | Content language | プラグマセットのデフォルト言語を設定します。 |
content-type
| エンコーディング宣言 | charsetを設定する代替形式です。
| |
default-style
| デフォルトスタイル | デフォルトのCSSスタイルシートセットの 名前を設定します。 | |
refresh
| リフレッシュ | タイマー付きのリダイレクトとして動作します。 | |
set-cookie
| No | Set-Cookie | 効果はありません。 |
x-ua-compatible
| X-UA-Compatible | 実際には、Internet Explorerが仕様により近づくよう促します。 | |
content-security-policy
| コンテンツセキュリティポリシー | コンテンツセキュリティポリシーを
Documentに適用します。
|
meta要素が
ドキュメントに挿入
される際に、そのhttp-equiv属性が
存在し、上記のいずれかの状態を表す場合、ユーザーエージェントは以下のリストに記載されているその状態に適したアルゴリズムを実行する必要があります。
http-equiv="content-language")
この機能は適合していません。著者は代わりにlang属性を使用することが推奨されます。
このプラグマはプラグマセットのデフォルト言語を設定します。 このようなプラグマが正常に処理されるまでは、 プラグマセットのデフォルト言語 は存在しません。
要素のcontent
属性に
U+002C COMMA 文字(,)が含まれている場合、処理を終了します。
inputを、要素のcontent
属性の値に設定します。
positionをinputの最初の文字を指すように設定します。
コードポイントのシーケンスを収集し、
それらがASCIIホワイトスペースでないことを確認します。
candidateを前のステップで得られた文字列に設定します。
candidateが空の文字列の場合、処理を終了します。
プラグマセットのデフォルト言語 をcandidateに設定します。
値が複数のスペース区切りトークンで構成されている場合、最初のトークン以外は無視されます。
このプラグマは、同じ名前を持つHTTP `Content-Language`
ヘッダーとはほとんど似ていません。
[HTTP]
http-equiv="content-type")
エンコーディング宣言の状態
は、charset
属性を設定する代替形式に過ぎません。これは
文字エンコーディング宣言
です。この状態のユーザーエージェント要件はすべて、仕様のパーセクションによって処理されます。
meta要素に
http-equiv
属性があり、その属性がエンコーディング宣言の状態である場合、
content属性の
値は次の文字列とASCII大小区別しない一致を持たなければなりません: "text/html;"。
オプションで、任意の数のASCIIホワイトスペースが続き、その後に
"charset=utf-8"が続きます。
ドキュメントには、meta
要素に
http-equiv
属性があり、その属性がエンコーディング宣言の状態であるものと、
charset
属性を持つ要素の両方を含めることはできません。
エンコーディング宣言の状態は
HTMLドキュメントで使用できますが、その状態の
http-equiv
属性を持つ要素は
XMLドキュメントでは使用できません。
http-equiv="default-style")
Support in one engine only.
このプラグマは、デフォルトのCSSスタイルシートセットの名前を 設定します。
優先CSSスタイルシートセット名を変更し、その名前を
要素のcontent
属性の値に設定します。
[CSSOM]
http-equiv="refresh")
このプラグマはタイマー付きリダイレクトとして機能します。
Documentオブジェクトには、
その関連付けられた宣言的リフレッシュを行う
(ブール値)があり、最初は false です。
inputを要素のcontent
属性の値に設定します。
共通の宣言的リフレッシュ手順
を、meta
要素のノードドキュメント、
input、およびmeta要素を使って実行します。
共通の宣言的リフレッシュ手順は、Documentオブジェクト
document、文字列input、およびオプションでmeta要素
metaを使用して以下のように行われます:
もしdocumentの宣言的リフレッシュを行うが true である場合、処理を終了します。
positionをinputの最初のコードポイントを指すように設定します。
timeを0に設定します。
コードポイントのシーケンスを収集し、 それらがASCII数字であることを確認します。 inputから収集されたものをtimeStringと呼びます。
もしtimeStringが空の文字列である場合、次のステップを実行します:
もしpositionが指すinputのコードポイントがU+002E (.)でない場合、処理を終了します。
そうでない場合、timeをtimeStringの解析結果に設定します。 非負整数の解析ルール を使用します。
コードポイントのシーケンスを収集し、 それらがASCII数字およびU+002E (.) 文字であることを確認します。 収集された文字は無視します。
urlRecordをdocumentのURLに設定します。
もしpositionがinputの末尾を超えていない場合、次のステップを実行します:
もしpositionが指すinputのコードポイントがU+003B (;)、U+002C (,)、 またはASCIIホワイトスペースでない場合、処理を終了します。
もしpositionが指すinputのコードポイントがU+003B (;)またはU+002C (,)である場合、 positionを次のコードポイントに進めます。
もしpositionがinputの末尾を超えていない場合、次のステップを実行します:
urlStringをinputのpositionから末尾までの部分文字列に設定します。
もしpositionが指すコードポイントがU+0055 (U)またはU+0075 (u)である場合、 positionを次のコードポイントに進めます。そうでない場合は、 skip quotesとラベル付けされたステップに進みます。
もしpositionが指すコードポイントがU+0052 (R)またはU+0072 (r)である場合、 positionを次のコードポイントに進めます。そうでない場合は、 parseとラベル付けされたステップに進みます。
もしpositionが指すコードポイントがU+004C (L)またはU+006C (l)である場合、 positionを次のコードポイントに進めます。そうでない場合は、 parseとラベル付けされたステップに進みます。
もしpositionが指すコードポイントがU+003D (=)である場合、 positionを次のコードポイントに進めます。 そうでない場合は、parseとラベル付けされたステップに進みます。
skip quotes: もしpositionが指すコードポイントがU+0027 (')またはU+0022 (")である場合、 quoteをそのコードポイントに設定し、positionを次の コードポイントに進めます。そうでない場合は、 quoteを空の文字列に設定します。
urlStringをinputのpositionから末尾までの部分文字列に設定します。
もしquoteが空の文字列でなく、urlString内にquoteと等しい コードポイントがある場合、 urlStringをその位置で切り詰めます。
parse: urlRecordをdocumentに相対的な urlStringのURLのエンコーディング解析 の結果に設定します。
もしurlRecordが失敗した場合、処理を終了します。
documentの宣言的リフレッシュを行うを true に設定します。
次のいずれかまたは複数のステップを実行します:
リフレッシュが完了した後(以下に定義)、
ユーザーがリダイレクトをキャンセルしておらず、
metaが指定されていて、documentのアクティブなサンドボックスフラグセット
にサンドボックス化された自動機能ブラウジングコンテキストフラグ
が設定されていない場合、navigate
を実行し、
documentのノードナビゲーブル
をurlRecordに使用して移動します。
documentを使用し、履歴の取り扱いを"置き換え"に設定します。
前の段落の目的のために、リフレッシュが完了したとされるのは、 次の2つの条件のうち後者のいずれかが発生したときです:
ここではmetaのノードドキュメントではなく、
documentを使用することが重要です。なぜなら、最初の手順セットと
リフレッシュが完了する間に変更される可能性があり、
metaが常に指定されるわけではない(HTTPの
`リフレッシュ`ヘッダーの場合など)からです。
ユーザーにインターフェースを提供し、それを選択すると、navigateを実行し、 documentのノードナビゲーブル をurlRecordに使用して移動します。
何もしません。
さらに、ユーザーエージェントは、タイマーの状態、タイマー付きリダイレクトの目的地など、 その操作のすべての側面について、ユーザーに通知することができます。
meta要素に
http-equiv
属性があり、その属性がリフレッシュ状態である場合、content
属性の値は次のいずれかでなければなりません:
URL"という文字列にASCII大小区別しない一致が続き、
U+003D EQUALS SIGN文字(=)が続き、その後に有効なURL文字列が続きます。
ただし、URL文字列は、リテラルのU+0027 APOSTROPHE(')またはU+0022 QUOTATION MARK(")文字で始まってはなりません。
前者の場合、整数はページがリロードされるまでの秒数を表し、後者の場合、整数はページが指定されたURLで置き換えられるまでの秒数を表します。
ニュース組織のフロントページは、次のようなマークアップをページのhead要素に含めることで、
ページが5分ごとにサーバーから自動的にリロードされることを保証できます:
< meta http-equiv = "Refresh" content = "300" >
ページの連続したスライドショーとして自動化するために、各ページを次のページにリフレッシュするために、 次のようなマークアップを使用することができます:
< meta http-equiv = "Refresh" content = "20; URL=page4.html" >
http-equiv="set-cookie")
このプラグマは適合しておらず、効果はありません。
ユーザーエージェントはこのプラグマを無視する必要があります。
http-equiv="x-ua-compatible")
実際には、このプラグマはInternet Explorerが仕様により近づくよう促します。
meta要素に
http-equiv
属性があり、その属性がX-UA-Compatible状態である場合、
content属性の
値は、"IE=edge"という文字列とASCII大小区別しない一致を持たなければなりません。
ユーザーエージェントはこのプラグマを無視する必要があります。
http-equiv="content-security-policy")
このプラグマはポリシーを適用し、
コンテンツセキュリティポリシーを
Documentに適用します。
[CSP]
policyを、コンテンツセキュリティポリシーのシリアライズされたコンテンツセキュリティポリシーの解析アルゴリズムの実行結果に設定します。
解析はmeta
要素の
content属性の値を使用し、
ソースを"meta"、ディスポジションを"enforce"とします。
policyから、report-uri、
frame-ancestors、
およびsandbox
指令をすべて削除します。
ポリシーを適用します。
meta要素に
http-equiv
属性があり、その属性がコンテンツセキュリティポリシー状態である場合、
content属性の
値は、
有効なコンテンツセキュリティポリシーでなければなりませんが、
その中にはreport-uri、
frame-ancestors、
またはsandbox
指令を含めることはできません。
content属性に与えられた
コンテンツセキュリティポリシーは現在のドキュメントに
適用されます。[CSP]
ドキュメントにmeta要素が
挿入される時点で、一部のリソースがすでに取得されている可能性があります。例えば、画像は、
meta要素に
http-equiv
属性があり、その属性がコンテンツセキュリティポリシー状態
である場合に、
利用可能な画像のリスト
に動的に挿入される前に保存されている可能性があります。すでに取得されたリソースが、後から
コンテンツセキュリティポリシーによってブロックされる保証はありません。
後から適用される場合です。
ページがクロスサイトスクリプティング攻撃のリスクを軽減するために、インラインJavaScriptの実行を防止し、 すべてのプラグインコンテンツをブロックするポリシーを選択する場合、次のようなポリシーを使用できます:
< meta http-equiv = "Content-Security-Policy" content = "script-src 'self'; object-src 'none'" >
ドキュメントに同じ状態を持つmeta要素が
同時に複数存在してはなりません。
文字エンコーディング宣言は、文書を保存または送信する際に使用される文字エンコーディングを指定するメカニズムです。
Encoding標準では、UTF-8 文字エンコーディングの使用を要求し、これを識別するために"utf-8" エンコーディングラベルを使用することを求めています。これらの要件により、文書の文字エンコーディング宣言が存在する場合、エンコーディングラベルが"utf-8"に対してASCII大文字小文字を区別しない一致で指定されることが必要です。文字エンコーディング宣言が存在するかどうかにかかわらず、文書のエンコードに使用される実際の文字エンコーディングはUTF-8でなければなりません。[ENCODING]
上記の規則を強制するために、オーサリングツールは新しく作成された文書に対してUTF-8をデフォルトとして使用しなければなりません。
次の制限も適用されます:
さらに、meta要素に関するいくつかの制限により、文書ごとにmetaベースの文字エンコーディング宣言は1つしか存在できません。
もしHTML文書がBOMで始まらず、そのエンコーディングがContent-Typeメタデータによって明示的に指定されておらず、文書がiframeのsrcdoc文書でない場合、エンコーディングはmeta要素とcharset属性、またはmeta要素とhttp-equiv属性を使用して指定する必要があります。これらの要素はエンコーディング宣言状態で使用される必要があります。
文字エンコーディング宣言は、すべての文字がASCII範囲内であっても必要です。なぜなら、フォーム内でユーザーによって入力された非ASCII文字やスクリプトによって生成されたURLなどを処理するために文字エンコーディングが必要だからです。
非UTF-8エンコーディングを使用すると、フォームの送信やURLエンコーディングに予期しない結果をもたらす可能性があります。デフォルトでは、これらは文書の文字エンコーディングを使用します。
文書がiframeのsrcdocドキュメントである場合、その文書には文字エンコーディング宣言を含めてはいけません。(この場合、ソースは既にデコードされています。なぜなら、それはiframeを含む文書の一部であるからです。)
XMLでは、必要に応じて、インライン文字エンコーディング情報にXML宣言を使用する必要があります。
HTMLでは、文字エンコーディングがUTF-8であることを宣言するために、作成者は次のマークアップを文書の上部(head要素内)に含めることができます:
< meta charset = "utf-8" >
XMLでは、代わりに文書の最上部にXML宣言を使用します:
<?xml version="1.0" encoding="utf-8"?>
style要素すべての現在のエンジンでサポートされています。
すべての現在のエンジンでサポートされています。
noscript 要素内で head 要素の子要素として使用されます。media — 適用されるメディアblocking — この要素が潜在的にレンダーブロックする可能性があるかどうかtitle 属性が特別な意味を持ちます:
CSSスタイルシートセット名
[Exposed =Window ]
interface HTMLStyleElement : HTMLElement {
[HTMLConstructor ] constructor ();
attribute boolean disabled ;
[CEReactions ] attribute DOMString media ;
[SameObject , PutForwards =value ] readonly attribute DOMTokenList blocking ;
// 廃止されたメンバーも含む
};
HTMLStyleElement includes LinkStyle ;
style要素は、作成者がドキュメントにCSSスタイルシートを埋め込むことを可能にします。style要素は、スタイル処理モデルの複数の入力の一つです。この要素は、ユーザーのためのコンテンツを表現するものではありません。
すべての現在のエンジンでサポートされています。
disabledのゲッターステップは次の通りです:
この要素に関連するCSSスタイルシートがない場合、falseを返します。
この要素の関連するCSSスタイルシートのdisabledフラグが設定されている場合、trueを返します。
falseを返します。
disabledのセッターステップは次の通りです:
この要素に関連するCSSスタイルシートがない場合、処理を終了します。
与えられた値がtrueである場合、この要素の関連するCSSスタイルシートのdisabledフラグを設定します。そうでない場合は、この要素の関連するCSSスタイルシートのdisabledフラグを解除します。
重要なのは、disabled属性の割り当ては、style要素に関連するCSSスタイルシートがある場合にのみ効果を発揮します:
const style = document. createElement( 'style' );
style. disabled = true ;
style. textContent = 'body { background-color: red; }' ;
document. body. append( style);
console. log( style. disabled); // false
media属性は、スタイルが適用されるメディアを指定します。値は有効なメディアクエリリストでなければなりません。ユーザーエージェントは、media属性の値が環境に一致する場合、またその他の関連条件が適用される場合にスタイルを適用し、それ以外の場合は適用しないようにする必要があります。
スタイルは、たとえばCSSの@mediaブロックの使用などで、さらに範囲が制限される場合があります。この仕様は、そうした追加の制限や要件を上書きするものではありません。
属性が省略された場合のデフォルトは「all」、つまりデフォルトでスタイルがすべてのメディアに適用されることを意味します。
blocking属性は、ブロッキング属性です。
1つのエンジンのみでサポートされています。
title属性は、style要素でCSSスタイルシートセットを定義します。style要素にtitle属性がない場合、その要素にはタイトルがありません。祖先のtitle属性は、style要素には適用されません。style要素がドキュメントツリー内にない場合、title属性は無視されます。[CSSOM]
style要素のtitle属性は、link要素のtitle属性と同様に、グローバルなtitle属性とは異なります。つまり、タイトルのないstyleブロックは親要素のタイトルを継承せず、単にタイトルを持たないということです。
style要素の子テキストコンテンツは、準拠したスタイルシートでなければなりません。
もしstyle要素がそのノード文書のパーサーによって作成された場合、その要素は暗黙的にレンダーブロックの可能性があると見なされます。
次のいずれかの条件が発生した場合、ユーザーエージェントはスタイルstyleブロックを更新するアルゴリズムを実行する必要があります:
要素がオープン要素のスタックからHTMLパーサーまたはXMLパーサーによってポップされたとき。
要素がオープン要素のスタックに含まれていないとき、そしてそれが接続されるまたは切断されるとき。
要素の子要素が変更された手順が実行されたとき。
スタイルstyleブロックを更新するアルゴリズムは次の通りです:
elementをstyle要素とする。
elementが関連付けられたCSSスタイルシートを持っている場合、該当するCSSスタイルシートを削除する。
elementが接続されていない場合は、処理を終了する。
elementのtype属性が存在し、その値が空文字列でもなく、"text/css"とASCII大文字小文字区別なく一致するわけでもない場合は、処理を終了する。
特に、"text/css; charset=utf-8"のようなパラメーターを持つtype値は、このアルゴリズムが早期に終了する原因となります。
Content
Security Policyによってインライン動作がブロックされるべきかどうかのアルゴリズムが、style要素、"style"、およびstyle要素の子テキストコンテンツに対して実行された際に"Blocked"を返す場合、処理を終了する。[CSP]
次のプロパティを持つCSSスタイルシートを作成する:
element
elementのmedia属性。
これは、現在存在しないかもしれない属性への参照であり、属性の現在の値のコピーではありません。CSSOMは、属性が動的に設定、変更、または削除されたときに何が起こるかを定義しています。
elementがドキュメントツリー内にある場合はtitle属性、それ以外の場合は空文字列。
これもまた、属性への参照です。
未設定。
設定済み。
null
デフォルト値のまま。
初期化されていないまま。
これは正しくないようです。おそらく要素の子テキストコンテンツを使用する必要があるでしょうか?問題#2997として追跡されています。
もしelementがスクリプトブロックスタイルシートに貢献する場合、elementをそのノードドキュメントのスクリプトブロックスタイルシートセットに追加する。
もしelementのmedia属性の値が環境に一致する場合、そしてelementが潜在的にレンダーブロックする場合、elementでのレンダリングをブロックする。
スタイルシートのクリティカルサブリソースを取得する試みが完了したとき、または、スタイルシートがクリティカルサブリソースを持たない場合、スタイルシートがパースおよび処理された後、ユーザーエージェントは次の手順を実行する必要があります:
クリティカルサブリソースの取得は明確に定義されていません; おそらく問題#968が最良の解決策でしょう。その間、クリティカルサブリソースリクエストは、style要素が現在レンダーブロックしているかどうかに応じてレンダーブロック設定を行うべきです。
elementをスタイルシートに関連付けられたstyle要素とする。
successをtrueとする。
何らかの理由(例:DNSエラー、HTTP 404レスポンス、接続の早期終了、サポートされていないコンテンツタイプ)でスタイルシートのクリティカルサブリソースの取得が失敗した場合、successをfalseに設定する。
コンテンツ固有のエラー、例:CSSパースエラーやPNGデコードエラーはsuccessに影響しません。
elementと次のステップを基に要素タスクをキューに入れる:
もしelementがスクリプトブロックスタイルシートに貢献している場合:
断言: elementのノードドキュメントのスクリプトブロックスタイルシートセットがelementを含んでいること。
elementをノードドキュメントのスクリプトブロックスタイルシートセットから削除する。
elementでレンダリングを解除する。
要素のロードイベントを遅延させる必要があります。要素のノードドキュメントがスタイルシートのクリティカルサブリソースをすべて取得する試みが完了するまで。
この仕様はスタイルシステムを指定していませんが、CSSはほとんどのウェブブラウザでサポートされることが予想されます。[CSS]
すべての現在のエンジンでサポートされています。
mediaおよびblockingIDL属性は、それぞれ同名のコンテンツ属性を反映する必要があります。
LinkStyleインターフェイスは、この要素でも実装されています。[CSSOM]
以下の文書では、強調表現がイタリック体の代わりに鮮やかな赤色のテキストでスタイルされ、作品のタイトルやラテン語の単語はデフォルトのイタリック体のままです。適切な要素を使用することで、ドキュメントの再スタイリングが容易になることが示されています。
<!DOCTYPE html>
< html lang = "en-US" >
< head >
< title > My favorite book</ title >
< style >
body { color : black ; background : white ; }
em { font-style : normal ; color : red ; }
</ style >
</ head >
< body >
< p > My < em > favorite</ em > book of all time has < em > got</ em > to be
< cite > A Cat's Life</ cite > . It is a book by P. Rahmel that talks
about the < i lang = "la" > Felis catus</ i > in modern human society.</ p >
</ body >
</ html >
スタイルシートが他のリソースを参照していない場合(例:style要素で指定された内部スタイルシートで@importルールがない場合)、スタイルルールは即座にスクリプトに対して利用可能にする必要があります。それ以外の場合は、スタイルルールはイベントループがレンダリングを更新する段階に達した時点でのみスクリプトに対して利用可能にする必要があります。
DocumentのコンテキストでHTMLパーサーまたはXMLパーサーにおいて、次のすべての条件が真である場合、要素elはスクリプトをブロックするスタイルシートを提供するとされます:
elがそのDocumentのパーサーによって作成されたこと。
elがstyle要素またはlink要素であり、パーサーによって作成された時点でスタイリング処理モデルに貢献する外部リソースリンクであったこと。
elのmedia属性の値が環境と一致すること。
要素がパーサーによって作成された時点で、elのスタイルシートが有効であったこと。
ユーザーエージェントがその特定のスタイルシートの読み込みをまだ諦めていないこと。ユーザーエージェントはいつでもスタイルシートの読み込みを諦めることができます。
スタイルシートの読み込みが完了する前に諦めると、最終的にスタイルシートが読み込まれた場合でも、スクリプトが誤った情報で動作する可能性があります。例えば、スタイルシートが要素の色を緑に設定するが、スタイルが適用される前にそれを検査するスクリプトが実行された場合、スクリプトは要素が黒(またはデフォルトの色)であることを検出し、それに基づいて誤った判断を下す可能性があります(例:ページの他の部分で黒を色として選択するなど)。実装者は、スクリプトが誤った情報を使用する可能性と、遅いネットワークリクエストが完了するまで何もしないことによるパフォーマンスへの影響をバランスさせる必要があります。
上記の規則の対応部分が<?xml-stylesheet?>PIにも適用されることが期待されています。ただし、これはまだ十分に調査されていません。
Documentには、最初は空の順序付きセットであるスクリプトをブロックするスタイルシートセットが含まれます。
Documentdocumentは、次の手順で真が返される場合、スクリプトをブロックするスタイルシートを持つとされます:
もしdocumentのスクリプトをブロックするスタイルシートセットが空でない場合は、真を返す。
もしdocumentのノードナビゲーブルがnullである場合は、偽を返す。
containerDocumentをdocumentのノードナビゲーブルのコンテナドキュメントとする。
もしcontainerDocumentがnullでなく、かつcontainerDocumentのスクリプトをブロックするスタイルシートセットが空でない場合は、真を返す。
偽を返す。
Documentは、スクリプトをブロックするスタイルシートを持たない場合にスクリプトをブロックするスタイルシートを持たないとされます。
Introduction_to_HTML/Document_and_website_structure#HTML_for_structuring_content
すべての現在のエンジンでサポートされています。
body要素すべての現在のエンジンでサポートされています。
すべての現在のエンジンでサポートされています。
html要素の2番目の要素として。body要素の開始タグは、要素が空であるか、body要素内の最初のものがASCIIホワイトスペースまたはコメントでない場合に省略できます。ただし、body要素内の最初のものがmeta、noscript、link、script、style、またはtemplate要素である場合を除きます。
body要素の終了タグは、body要素の直後にコメントがない場合に省略できます。onafterprint
onbeforeprint
onbeforeunload
onhashchange
onlanguagechange
onmessage
onmessageerror
onoffline
ononlineonpageswap
onpagehide
onpagereveal
onpageshow
onpopstate
onrejectionhandled
onstorage
onunhandledrejection
onunload[Exposed =Window ]
interface HTMLBodyElement : HTMLElement {
[HTMLConstructor ] constructor ();
// 過去のメンバーも含む
};
HTMLBodyElement includes WindowEventHandlers ;
適合する文書には、body要素が1つだけ存在します。document.bodyIDL属性は、スクリプトが文書のbody要素に簡単にアクセスできるようにします。
一部のDOM操作(例えば、ドラッグアンドドロップモデルの一部)は、"body要素"の用語で定義されています。これは、DOM内の特定の要素を指しており、任意のbody要素ではありません。
body要素は、イベントハンドラーコンテンツ属性として、イベントハンドラーの一部を公開します。また、それらのイベントハンドラーIDL属性をミラーリングします。
Windowオブジェクトのイベントハンドラーは、Window-reflecting
body要素イベントハンドラーセットによって命名され、body要素上で公開され、通常HTML要素でサポートされる同じ名前の汎用イベントハンドラーを置き換えます。
したがって、例えば、errorイベントがDocumentのbody要素の子で発生し、バブリングされた場合、そのイベントはまずその要素のonerrorのイベントハンドラーコンテンツ属性をトリガーし、その後にルートhtml要素のそれをトリガーし、その後、onerrorのイベントハンドラーコンテンツ属性をトリガーします。これは、イベントがターゲットから、body、html、Document、Windowにバブリングされ、イベントハンドラーがWindowを監視していて、bodyを監視していないためです。しかし、addEventListener()を使用してbodyにアタッチされた通常のイベントリスナーは、イベントがWindowオブジェクトに到達したときではなく、bodyを通過したときに実行されます。
このページでは、ユーザーがオンラインかオフラインかを示すインジケーターを更新します:
<!DOCTYPE HTML>
< html lang = "en" >
< head >
< title > オンラインかオフラインか?</ title >
< script >
function update( online) {
document. getElementById( 'status' ). textContent =
online ? 'オンライン' : 'オフライン' ;
}
</ script >
</ head >
< body ononline = "update(true)"
onoffline = "update(false)"
onload = "update(navigator.onLine)" >
< p > You are: < span id = "status" > (不明)</ span ></ p >
</ body >
</ html >
article 要素すべての現在のエンジンでサポートされています。
HTMLElement を使用します。
article
要素は、ドキュメント、ページ、アプリケーション、またはサイト内で独立して配布可能または再利用可能な、完全または自己完結型のコンテンツを表します。これは、たとえばフォーラム投稿、雑誌や新聞の記事、ブログ記事、ユーザーが投稿したコメント、インタラクティブなウィジェットやガジェット、または他の独立したコンテンツ項目である可能性があります。
article
要素が入れ子になっている場合、内側の article 要素は、外側の article
の内容に原則として関連する記事を表します。たとえば、ユーザーが投稿したコメントを受け入れるサイトのブログ記事は、ブログ記事のために article
要素内に入れ子になっている要素として、コメントを article 要素として表すことができます。
article
要素に関連する著者情報(address
要素を参照)は、入れ子になった article 要素には適用されません。
特にシンジケーションで再配布されるコンテンツで使用される場合、article 要素は、Atom の
entry 要素に似た目的を持ちます。[ATOM]
schema.org マイクロデータ語彙は、CreativeWork のサブタイプの1つを使用して、article
要素の発行日を提供するために使用できます。
ページの主な内容(フッター、ヘッダー、ナビゲーションブロック、サイドバーを除く)がすべて1つの自己完結型の構成である場合、その内容は article
でマークされる場合がありますが、その場合は技術的には冗長です(ページが単一の構成であることは自明であり、それは単一のドキュメントであるためです)。
この例では、article
要素を使用してブログ記事を表示し、いくつかの schema.org 注釈を含んでいます:
< article itemscope itemtype = "http://schema.org/BlogPosting" >
< header >
< h2 itemprop = "headline" > 人生で最も重要なルール</ h2 >
< p >< time itemprop = "datePublished" datetime = "2009-10-09" > 3日前</ time ></ p >
< link itemprop = "url" href = "?comments=0" >
</ header >
< p > マイクが近くにある場合、何を言っているかが全世界に送信されていると考えてください。真剣に。</ p >
</ p > ...</ p >
< footer >
< a itemprop = "discussionUrl" href = "?comments=1" > コメントを見る...</ a >
</ footer >
</ article >
こちらは同じブログ投稿ですが、いくつかのコメントを表示しています:
< article itemscope itemtype = "http://schema.org/BlogPosting" >
< header >
< h2 itemprop = "headline" > 人生で最も重要なルール</ h2 >
< p >< time itemprop = "datePublished" datetime = "2009-10-09" > 3日前</ time ></ p >
< link itemprop = "url" href = "?comments=0" >
</ header >
< p > マイクが近くにある場合、何を言っているかが全世界に送信されていると考えてください。真剣に。</ p >
</ p > ...</ p >
< section >
< h1 > コメント</ h1 >
< article itemprop = "comment" itemscope itemtype = "http://schema.org/Comment" id = "c1" >
< link itemprop = "url" href = "#c1" >
</ footer >
< p > 投稿者: < span itemprop = "creator" itemscope itemtype = "http://schema.org/Person" >
< span itemprop = "name" > ジョージ・ワシントン</ span >
</ span ></ p >
< p >< time itemprop = "dateCreated" datetime = "2009-10-10" > 15分前</ time ></ p >
</ footer >
</ p > そうですね!特にロビイストの友達の話をしているときに!</ p >
</ article >
</ article itemprop = "comment" itemscope itemtype = "http://schema.org/Comment" id = "c2" >
< link itemprop = "url" href = "#c2" >
</ footer >
< p > 投稿者: < span itemprop = "creator" itemscope itemtype = "http://schema.org/Person" >
< span itemprop = "name" > ジョージ・ハモンド</ span >
</ span ></ p >
< p >< time itemprop = "dateCreated" datetime = "2009-10-10" > 5分前</ time ></ p >
</ footer >
</ p > へえ、君と同じ名前だね。</ p >
</ article >
</ section >
</ article >
各コメントの情報(投稿者や日時など)を提供するために footer
要素が使用されていることに注目してください。この要素は、適切な場合にセクションの冒頭に表示することができます。このケースでは header
を使用しても問題はありません。これは主に著者の好みの問題です。
この例では、article
要素がポータルページのウィジェットをホストするために使用されています。ウィジェットは、特定のスタイルとスクリプトされた動作を取得するために、カスタマイズされたビルトイン要素 として実装されています。
<!DOCTYPE HTML>
< html lang = en >
< title > eHome Portal</ title >
< script src = "/scripts/widgets.js" ></ script >
< link rel = stylesheet href = "/styles/main.css" >
< article is = "stock-widget" >
< h2 > Stocks</ h2 >
< table >
< thead > < tr > < th > Stock < th > Value < th > Delta
< tbody > < template > < tr > < td > < td > < td > </ template >
</ table >
< p > < input type = button value = "Refresh" onclick = "this.parentElement.refresh()" >
</ article >
</ article is = "news-widget" >
< h2 > News</ h2 >
< ul >
< template > < li > < p >< img > < strong ></ strong > </ p > </ p > </ template > </ ul > </ p > </ article >
section 要素すべての現在のエンジンでサポートされています。
HTMLElementを使用します。section要素は、文書またはアプリケーションの一般的なセクションを表します。このコンテキストでのセクションは、通常、見出しを伴うテーマごとのグループ化を指します。
セクションの例としては、章、タブ付きダイアログボックスのさまざまなタブページ、または論文の番号付きセクションがあります。ウェブサイトのホームページは、イントロダクション、ニュース項目、お問い合わせ情報などのセクションに分割することができます。
著者は、article要素の代わりに、section要素を使用することを推奨します。
section要素は、汎用的なコンテナ要素ではありません。要素がスタイリング目的でのみ必要である場合や、スクリプトの便宜上必要な場合、著者は代わりにdiv要素を使用することが推奨されます。一般的なルールとして、section要素は、要素の内容が文書のアウトラインに明示的にリストされる場合にのみ適しています。
以下の例では、リンゴに関する記事(より大きなウェブページの一部)が表示されており、2つの短いセクションが含まれています。
< article >
< hgroup >
< h2 > リンゴ</ h2 >
< p > 美味しくておいしい果物!</ p >
</ hgroup >
< p > リンゴはリンゴの木の果実です。</ p > < section >
< h3 > レッドデリシャス</ h3 >
< p > これらの明るい赤色のリンゴは、多くのスーパーマーケットで最も一般的に見られるものです。</ p >
</ section >
< section >
< h3 > グラニースミス</ h3 >
< p > これらのジューシーで緑色のリンゴは、アップルパイの素晴らしいフィリングになります。</ p >
</ section >
</ article >
以下は、卒業生のリストと式典の説明の2つのセクションを持つ卒業式プログラムです。(この例のマークアップは、要素間の空白を最小限に抑えるために時折使用される珍しいスタイルが特徴です。)
<!DOCTYPE Html>
< Html Lang = En >
< Head >
< Title > Graduation Ceremony Summer 2022</ Title >
</ Head >
< Body >
< H1 > 卒業式</ H1 >
< Section >
< H2 > 式典</ H2 >
< P > 入場行進</ P >
< P > 卒業生代表挨拶</ P >
< P > 生徒会長挨拶</ P >
< P > 卒業証書授与</ P >
< P > 校長の閉会挨拶</ P >
</ Section >
< Section >
< H2 > 卒業生</ H2 >
< Ul >
< Li > モリー・カーペンター</ Li >
< Li > アナスタシア・ルッチオ</ Li >
< Li > エベネザー・マッコイ</ Li >
< Li > カリン・マーフィー</ Li >
< Li > トーマス・レイス</ Li >
< Li > スーザン・ロドリゲス</ Li >
</ Ul >
</ Section >
</ Body >
</ Html >
この例では、著者がいくつかのセクションを章として、いくつかを付録としてマークアップし、CSSを使用してこれら2つのクラスのセクションのヘッダーを異なるスタイルにしています。
< style >
section { border : double medium ; margin : 2 em ; }
section . chapter h2 { font : 2 em Roboto , Helvetica Neue , sans-serif ; }
section . appendix h2 { font : small-caps 2 em Roboto , Helvetica Neue , sans-serif ; }
</ style >
< header >
< hgroup >
< h1 > 私の本</ h1 >
< p > あまり内容のないサンプル</ p >
</ hgroup >
< p >< small > Dummy Publicorp Ltd. 発行</ small ></ p >
</ header >
< section class = "chapter" >
< h2 > 私の最初の章</ h2 >
< p > これは私の章の最初のものです。あまり多くは語りません。</ p >
< p > しかし、2つの段落があります!</ p >
</ section >
< section class = "chapter" >
< h2 > 続く:第2章</ h2 >
< p > ブラ・ディ・ブラ、ディ・ブラ・ディ・ブラ。ブーム。</ p >
</ section >
< section class = "chapter" >
< h2 > 第3章:さらなる例</ h2 >
< p > 明るい色とアーストーンの戦いが気付かれないことはありません。</ p >
< p > しかし、それが私の物語を台無しにするかもしれません。</ p >
</ section >
< section class = "appendix" >
< h2 > 付録A:例の概要</ h2 >
< p > これらはデモンストレーションです。</ p >
</ section >
< section class = "appendix" >
< h2 > 付録B:いくつかの結論的な発言</ h2 >
< p > この長い例が、セクションが実際のセクションを示すために使用される限り、スタイル設定が可能であることを示していることを願っています。</ p >
</ section >
nav要素すべての現在のエンジンでサポートされています。
HTMLElementを使用します。
nav要素は、ページの他の部分や他のページへのリンクを含むセクションを表します:
ナビゲーションリンクを持つセクションです。
ページ内のすべてのリンクグループがnav要素に含まれる必要はありません—この要素は主に主要なナビゲーションブロックで構成されるセクションを意図しています。特に、フッターには、利用規約、ホームページ、著作権ページなど、サイトのさまざまなページへの短いリンクリストが含まれることがよくあります。このような場合、footer要素のみで十分です; このような場合にはnav要素を使用することもできますが、通常は不要です。
ナビゲーション情報の初期表示を省略することが役立つユーザー、またはナビゲーション情報を即座に利用可能にすることが役立つユーザーを対象としたユーザーエージェント(スクリーンリーダーなど)は、この要素を使用して、ページのどのコンテンツを最初にスキップするか、またはリクエストに応じて提供するか(またはその両方)を判断することができます。
次の例では、nav要素が2つあり、1つはサイト全体の主要ナビゲーション用で、もう1つはページ自体の二次ナビゲーション用です。
< body >
< h1 > The Wiki Center Of Exampland</ h1 >
< nav >
< ul >
< li >< a href = "/" > Home</ a ></ li >
< li >< a href = "/events" > Current Events</ a ></ li >
...more...
</ ul >
</ nav >
< article >
< header >
< h2 > Demos in Exampland</ h2 >
< p > Written by A. N. Other.</ p >
</ header >
< nav >
< ul >
< li >< a href = "#public" > Public demonstrations</ a ></ li >
< li >< a href = "#destroy" > Demolitions</ a ></ li >
...more...
</ ul >
</ nav >
< div >
< section id = "public" >
< h2 > Public demonstrations</ h2 >
< p > ...more...</ p >
</ section >
< section id = "destroy" >
< h2 > Demolitions</ h2 >
< p > ...more...</ p >
</ section >
...more...
</ div >
</ footer >
< p >< a href = "?edit" > Edit</ a > | < a href = "?delete" > Delete</ a > | < a href = "?Rename" > Rename</ a ></ p >
</ footer >
</ article >
</ footer >
< p >< small > © copyright 1998 Exampland Emperor</ small ></ p >
</ footer >
</ body >
次の例では、ページにいくつかのリンクが存在する場所がありますが、これらの場所のうち1つだけがナビゲーションセクションと見なされます。
< body itemscope itemtype = "http://schema.org/Blog" >
< header >
< h1 > Wake up sheeple!</ h1 >
< p >< a href = "news.html" > News</ a > -
< a href = "blog.html" > Blog</ a > -
< a href = "forums.html" > Forums</ a ></ p >
< p > Last Modified: < span itemprop = "dateModified" > 2009-04-01</ span ></ p >
< nav >
< h2 > Navigation</ h2 >
< ul >
< li >< a href = "articles.html" > Index of all articles</ a ></ li >
< li >< a href = "today.html" > Things sheeple need to wake up for today</ a ></ li >
< li >< a href = "successes.html" > Sheeple we have managed to wake</ a ></ li >
</ ul >
</ nav >
</ header >
< main >
< article itemprop = "blogPosts" itemscope itemtype = "http://schema.org/BlogPosting" >
< header >
< h2 itemprop = "headline" > My Day at the Beach</ h2 >
</ header >
< div itemprop = "articleBody" >
< p > Today I went to the beach and had a lot of fun.</ p >
...more content...
</ div >
< footer >
< p > Posted < time itemprop = "datePublished" datetime = "2009-10-10" > Thursday</ time > .</ p >
</ footer >
</ article >
...more blog posts...
</ main >
</ footer >
< p > Copyright ©
< span itemprop = "copyrightYear" > 2010</ span >
< span itemprop = "copyrightHolder" > The Example Company</ span >
</ p >
< p >< a href = "about.html" > About</ a > -
< a href = "policy.html" > Privacy Policy</ a > -
< a href = "contact.html" > Contact Us</ a ></ p >
</ footer >
</ body >
上記の例では、microdataの注釈もあり、ブログ記事の日付やその他のメタデータをschema.orgの語彙を使用して提供しています。
nav要素はリストを含む必要はなく、他の種類のコンテンツを含むこともできます。このナビゲーションブロックでは、リンクが文章で提供されています:
< nav >
< h1 > Navigation</ h1 >
< p > You are on my home page. To the north lies < a href = "/blog" > my
blog</ a > , from whence the sounds of battle can be heard. To the east
you can see a large mountain, upon which many < a
href = "/school" > school papers</ a > are littered. Far up thus mountain
you can spy a little figure who appears to be me, desperately
scribbling a < a href = "/school/thesis" > thesis</ a > .</ p >
< p > To the west are several exits. One fun-looking exit is labeled < a
href = "https://games.example.com/" > "games"</ a > . Another more
boring-looking exit is labeled < a
href = "https://isp.example.net/" > ISP™</ a > .</ p >
< p > To the south lies a dark and dank < a href = "/about" > contacts
page</ a > . Cobwebs cover its disused entrance, and at one point you
see a rat run quickly out of the page.</ p >
</ nav >
この例では、nav要素がメールアプリケーションで使用され、ユーザーがフォルダーを切り替えることができます:
< p >< input type = button value = "Compose" onclick = "compose()" ></ p >
< nav >
< h1 > フォルダー</ h1 >
< ul >
< li > < a href = "/inbox" onclick = "return openFolder(this.href)" > 受信トレイ</ a > < span class = count ></ span >
</ li > < li > < a href = "/sent" onclick = "return openFolder(this.href)" > 送信済み</ a >
</ li > < li > < a href = "/drafts" onclick = "return openFolder(this.href)" > 下書き</ a >
</ li > < li > < a href = "/trash" onclick = "return openFolder(this.href)" > ごみ箱</ a >
</ li > < li > < a href = "/customers" onclick = "return openFolder(this.href)" > 顧客</ a >
</ ul >
</ nav >
aside要素すべての現在のエンジンでサポートされています。
HTMLElementを使用します。
aside要素は、その周りのコンテンツに対して間接的に関連するセクションを表し、そのコンテンツから分離していると見なすことができます。このようなセクションは、印刷されたタイポグラフィではサイドバーとしてよく表現されます。
この要素は、引用やサイドバー、広告、nav要素のグループ、またはページのメインコンテンツとは別のコンテンツとして考えられる他のコンテンツのために使用できます。
括弧書きのように、本文の流れの一部である場合にaside要素を使用するのは適切ではありません。
次の例は、長いヨーロッパに関するニュース記事の中で、スイスに関する背景資料をマークアップするためにasideが使用されている例を示しています。
< aside >
< h2 > Switzerland</ h2 >
< p > Switzerland, a land-locked country in the middle of geographic
Europe, has not joined the geopolitical European Union, though it is
a signatory to a number of European treaties.</ p >
</ aside >
次の例は、長い記事の中で引用をマークアップするためにasideが使用されている例を示しています。
...
< p > He later joined a large company, continuing on the same work.
< q > I love my job. People ask me what I do for fun when I'm not at
work. But I'm paid to do my hobby, so I never know what to
answer. Some people wonder what they would do if they didn't have to
work... but I know what I would do, because I was unemployed for a
year, and I filled that time doing exactly what I do now.</ q ></ p >
< aside >
< q > People ask me what I do for fun when I'm not at work. But I'm
paid to do my hobby, so I never know what to answer.</ q >
</ aside >
< p > Of course his work — or should that be hobby? —
isn't his only passion. He also enjoys other pleasures.</ p >
...
次の抜粋は、ブログのブログロールやその他のサイドコンテンツのためにasideがどのように使用できるかを示しています:
< body >
< header >
< h1 > My wonderful blog</ h1 >
< p > My tagline</ p >
</ header >
< aside >
<!-- this aside contains two sections that are tangentially related
to the page, namely, links to other blogs, and links to blog posts
from this blog -->
< nav >
< h2 > My blogroll</ h2 >
< ul >
< li >< a href = "https://blog.example.com/" > Example Blog</ a >
</ ul >
</ nav >
< nav >
< h2 > Archives</ h2 >
< ol reversed >
< li >< a href = "/last-post" > My last post</ a >
< li >< a href = "/first-post" > My first post</ a >
</ ol >
</ nav >
</ aside >
< aside >
<!-- this aside is tangentially related to the page also, it
contains twitter messages from the blog author -->
< h1 > Twitter Feed</ h1 >
< blockquote cite = "https://twitter.example.net/t31351234" >
I'm on vacation, writing my blog.
</ blockquote >
< blockquote cite = "https://twitter.example.net/t31219752" >
I'm going to go on vacation soon.
</ blockquote >
</ aside >
< article >
<!-- this is a blog post -->
< h2 > My last post</ h2 >
< p > This is my last post.</ p >
< footer >
< p >< a href = "/last-post" rel = bookmark > Permalink</ a >
</ footer >
</ article >
< article >
<!-- this is also a blog post -->
< h2 > My first post</ h2 >
< p > This is my first post.</ p >
< aside >
<!-- this aside is about the blog post, since it's inside the
<article> element; it would be wrong, for instance, to put the
blogroll here, since the blogroll isn't really related to this post
specifically, only to the page as a whole -->
< h2 > Posting</ h2 >
< p > While I'm thinking about it, I wanted to say something about
posting. Posting is fun!</ p >
</ aside >
< footer >
< p >< a href = "/first-post" rel = bookmark > Permalink</ a >
</ footer >
</ article >
< footer >
< p >< a href = "/archives" > Archives</ a > -
< a href = "/about" > About me</ a > -
< a href = "/copyright" > Copyright</ a ></ p >
</ footer >
</ body >
h1、h2、h3、h4、h5 および h6 要素すべての現在のエンジンでサポートされています。
すべての現在のエンジンでサポートされています。
すべての現在のエンジンでサポートされています。
すべての現在のエンジンでサポートされています。
すべての現在のエンジンでサポートされています。
すべての現在のエンジンでサポートされています。
すべての現在のエンジンでサポートされています。
hgroup要素の子要素として。
[Exposed =Window ]
interface HTMLHeadingElement : HTMLElement {
[HTMLConstructor ] constructor ();
// also has obsolete members
};
これらの要素は、そのセクションの見出しを表します。
これらの要素のセマンティクスと意味は、見出しとアウトラインのセクションで定義されています。
これらの要素は、その名前にある数字によって見出しレベルが決まります。
見出しレベルは、ネストされたセクションのレベルに対応しています。
h1
要素はトップレベルセクション用であり、
h2
はサブセクション用、h3は
サブサブセクション用です。
それぞれのドキュメントのアウトライン(見出しとセクション構造)に関しては、これらの2つのスニペットはセマンティクス的に等価です。
< body >
< h1 > Let's call it a draw(ing surface)</ h1 >
< h2 > Diving in</ h2 >
< h2 > Simple shapes</ h2 >
< h2 > Canvas coordinates</ h2 >
< h3 > Canvas coordinates diagram</ h3 >
< h2 > Paths</ h2 >
</ body >
< body >
< h1 > Let's call it a draw(ing surface)</ h1 >
< section >
< h2 > Diving in</ h2 >
</ section >
< section >
< h2 > Simple shapes</ h2 >
</ section >
< section >
< h2 > Canvas coordinates</ h2 >
< section >
< h3 > Canvas coordinates diagram</ h3 >
</ section >
</ section >
< section >
< h2 > Paths</ h2 >
</ section >
</ body >
作成者は、簡潔さのために前者のスタイルを好むか、追加のスタイリングフックのために後者のスタイルを好むかもしれません。どちらが最良かは、単に好まれる作成スタイルの問題です。
hgroup 要素すべての現在のエンジンでサポートされています。
p要素が続き、次に 1 つのh1、
h2、
h3、
h4、
h5、
またはh6
要素が続き、その後に 0 個以上の p要素が続き、必要に応じてスクリプトサポート要素と混在します。
HTMLElementを使用します。
hgroup要素は、見出しと関連コンテンツを表します。この要素は、h1–h6要素と
1 つ以上のp要素をグループ化して、サブ見出し、代替タイトル、またはキャッチフレーズを表すコンテンツを含めるために使用できます。
ここに、hgroup要素に含まれる有効な見出しの例をいくつか示します。
< hgroup >
< h1 > The reality dysfunction</ h1 >
< p > Space is not the only void</ p >
</ hgroup >
< hgroup >
< h1 > Dr. Strangelove</ h1 >
< p > Or: How I Learned to Stop Worrying and Love the Bomb</ p >
</ hgroup >
header 要素すべての現在のエンジンでサポートされています。
headerまたはfooter要素の子孫を含まないこと。
HTMLElementを使用します。
header要素は、紹介やナビゲーションの補助要素のグループを表します。
header要素は通常、見出し (h1–h6要素やhgroup要素)を含むことを意図していますが、これは必須ではありません。header要素は、セクションの目次、検索フォーム、または関連するロゴをラップするためにも使用できます。
いくつかのサンプルヘッダーを紹介します。これは、ゲーム用の最初のものです。
< header >
< p > Welcome to...</ p >
< h1 > Voidwars!</ h1 >
</ header >
次のスニペットは、要素が仕様のヘッダーをマークアップするためにどのように使用できるかを示しています。
< header >
< hgroup >
< h1 > Fullscreen API</ h1 >
< p > 現行標準 — 最終更新日 2015年10月19日</ p >
</ hgroup >
< dl >
< dt > 参加:</ dt >
< dd >< a href = "https://github.com/whatwg/fullscreen" > GitHub whatwg/fullscreen</ a ></ dd >
< dt > コミット:</ dt >
< dd >< a href = "https://github.com/whatwg/fullscreen/commits" > GitHub whatwg/fullscreen/commits</ a ></ dd >
</ dl >
</ header >
header要素はセクショニングコンテンツではありません;
新しいセクションを導入しません。
この例では、ページにはh1要素によって与えられたページの見出しがあり、h2要素によって与えられた
2 つのサブセクションがあります。header要素の後のコンテンツは、header要素で開始された最後のサブセクションの一部です。なぜなら、header要素はアウトラインアルゴリズムに関与しないためです。
< body >
< header >
< h1 > Little Green Guys With Guns</ h1 >
< nav >
< ul >
< li >< a href = "/games" > Games</ a >
< li >< a href = "/forum" > Forum</ a >
< li >< a href = "/download" > Download</ a >
</ ul >
</ nav >
< h2 > Important News</ h2 > <!-- これが2つ目のサブセクションを開始します -->
<!-- これは「Important News」というタイトルのサブセクションの一部です -->
< p > 今日のゲームをプレイするには、クライアントを更新する必要があります。</ p >
< h2 > Games</ h2 > <!-- これが3つ目のサブセクションを開始します -->
</ header >
< p > あなたには 3 つのアクティブなゲームがあります:</ p >
<!-- これはまだ「Games」というタイトルのサブセクションの一部です -->
...
footer 要素すべての現在のエンジンでサポートされています。
headerまたはfooter要素の子孫を含まないこと。
HTMLElementを使用します。
footer要素は、最も近い先祖セクショニングコンテンツ要素、またはそのような先祖がない場合は本文要素のフッターを表します。フッターには通常、そのセクションに関する情報(誰が書いたか、関連文書へのリンク、著作権データなど)が含まれます。
footer要素にセクション全体が含まれている場合、それらは付録、索引、長いコロフォン、詳細なライセンス契約、およびその他のそのような内容を表します。
セクションの著者または編集者の連絡先情報は、address要素に含めるべきであり、場合によってはfooter内に配置されることもあります。署名や他の情報はheaderまたはfooterのいずれにも(あるいはどちらにも)配置できます。これらの要素の主な目的は、単に作成者が説明的なマークアップを書きやすく、維持およびスタイル設定しやすくすることです。特定の構造を作成者に強制することを意図しているわけではありません。
フッターは必ずしもセクションの終わりに表示される必要はありませんが、通常は表示されます。
先祖セクショニングコンテンツ要素がない場合、ページ全体に適用されます。
footer要素はそれ自体がセクショニングコンテンツではありません;
新しいセクションを導入しません。
次に、上部と下部に同じコンテンツを持つ 2 つのフッターがあるページの例を示します。
< body >
< footer >< a href = "../" > 目次に戻る...</ a ></ footer >
< hgroup >
< h1 > Lorem ipsum</ h1 >
< p > The ipsum of all lorems</ p >
</ hgroup >
< p > A dolor sit amet, consectetur adipisicing elit, sed do eiusmod
tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim
veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex
ea commodo consequat. Duis aute irure dolor in reprehenderit in
voluptate velit esse cillum dolore eu fugiat nulla
pariatur. Excepteur sint occaecat cupidatat non proident, sunt in
culpa qui officia deserunt mollit anim id est laborum.</ p >
< footer >< a href = "../" > 目次に戻る...</ a ></ footer >
</ body >
次の例は、footer要素が、サイト全体のフッターとセクションのフッターの両方に使用されていることを示しています。
<!DOCTYPE HTML>
< HTML LANG = "en" >< HEAD >
< TITLE > The Ramblings of a Scientist</ TITLE >
< BODY >
< H1 > The Ramblings of a Scientist</ H1 >
< ARTICLE >
< H1 > Episode 15</ H1 >
< VIDEO SRC = "/fm/015.ogv" CONTROLS PRELOAD >
< P >< A HREF = "/fm/015.ogv" > ビデオをダウンロードする</ A > .</ P >
</ VIDEO >
< FOOTER > <!-- 記事のフッター -->
< P > 公開日時 < TIME DATETIME = "2009-10-21T18:26-07:00" > 2009/10/21 午後 6:26</ TIME ></ P >
</ FOOTER >
</ ARTICLE >
< ARTICLE >
< H1 > 私の好きな列車</ H1 >
< P > 私は列車が大好きです。私が一番好きな列車はコーフです。</ P >
< P > 石炭車を引いているのを見るのは楽しいです。それは非常に小さく見えるからです。</ P >
< FOOTER > <!-- 記事のフッター -->
< P > 公開日時 < TIME DATETIME = "2009-09-15T14:54-07:00" > 2009/09/15 午後 2:54</ TIME ></ P >
</ FOOTER >
</ ARTICLE >
< FOOTER > <!-- サイト全体のフッター -->
< NAV >
< P >< A HREF = "/credits.html" > クレジット</ A > —
< A HREF = "/tos.html" > サービス利用規約</ A > —
< A HREF = "/index.html" > ブログインデックス</ A ></ P >
</ NAV >
< P > 著作権 © 2009 ゴードン・フリーマン</ P >
</ FOOTER >
</ BODY >
</ HTML >
いくつかのサイトデザインには、「ファットフッター」と呼ばれることがあるものがあります — 多くの素材を含むフッターで、画像、他の記事へのリンク、フィードバックを送信するページへのリンク、特別オファーなどが含まれることがあります。ある意味、フッターに「トップページ全体」があるようなものです。
この断片は、「ファットフッター」を持つサイトのページの底部を示しています。
...
< footer >
< nav >
< section >
< h1 > 記事</ h1 >
< p >< img src = "images/somersaults.jpeg" alt = "" > ジムと一緒に
私たちの宙返りクラス!この二部構成の記事で、ジムがペースを取り戻す方法を教えてくれます。< a href = "articles/somersaults/1" > パート1</ a > · < a href = "articles/somersaults/2" > パート2</ a ></ p >
< p >< img src = "images/kindplus.jpeg" > 崖の端を歩くのに疲れた?私たちのゲストライター、ララがバーを通過する方法を教えてくれます。< a href = "articles/kindplus/1" > 続きを読む...</ a ></ p >
< p >< img src = "images/crisps.jpeg" > チップはもうダメです、残っているのはジャガイモだけです。それをどうしますか? < a
href = "articles/crisps/1" > 続きを読む...</ a ></ p >
</ section >
< ul >
< li >< a href = "/about" > 私たちについて...</ a >
< li >< a href = "/feedback" > フィードバックを送る!</ a >
< li >< a href = "/sitemap" > サイトマップ</ a >
</ ul >
</ nav >
< p >< small > 著作権 © 2015 The Snacker —
< a href = "/tos" > サービス利用規約</ a ></ small ></ p >
</ footer >
</ body >
address 要素すべての現在のエンジンでサポートされています。
header、
footer、または
address
要素の子孫を含めることはできません。
HTMLElement を使用します。
address 要素は、その最も近い
article または body 要素の祖先の連絡先情報を表します。それが body 要素 である場合、連絡先情報は文書全体に適用されます。
例えば、HTML に関連する W3C ウェブサイトのページには、次のような連絡先情報が含まれる場合があります。
< ADDRESS >
< A href = "../People/Raggett/" > Dave Raggett</ A > ,
< A href = "../People/Arnaud/" > Arnaud Le Hors</ A > ,
contact persons for the < A href = "Activity" > W3C HTML Activity</ A >
</ ADDRESS >
address
要素は、任意の住所(例えば、郵送先住所)を表すために使用してはなりません。ただし、それらの住所が関連する連絡先情報である場合を除きます。(一般的な郵送先住所をマークアップするには、p 要素が適しています。)
address
要素には、連絡先情報以外の情報を含めてはなりません。
例えば、次のものは address
要素の不適合な使用です。
< ADDRESS > Last Modified: 1999/12/24 23:37:50</ ADDRESS >
通常、address 要素は、footer 要素に他の情報と共に含まれます。
ノード node の連絡先情報は、次のリストから最初に適用される項目によって定義された address 要素のコレクションです。
article 要素の場合
body
要素の場合
連絡先情報は、node を祖先とし、他の body 要素または article
要素の祖先を持たない address 要素です。
article 要素がある場合
body 要素がある場合
node には連絡先情報がありません。
ユーザーエージェントは、ノードの連絡先情報をユーザーに公開したり、セクションを連絡先情報に基づいてインデックスするなど、他の目的で使用することがあります。
この例では、フッターには連絡先情報と著作権表示が含まれています。
< footer >
< address >
For more details, contact
< a href = "mailto:js@example.com" > John Smith</ a > .
</ address >
< p >< small > © copyright 2038 Example Corp.</ small ></ p >
</ footer >
h1–h6
要素には、その要素名の数字によって決まる見出しレベルがあります。
これらの要素は見出しを表します。見出しの 見出しレベルが低いほど、その見出しの祖先セクションが少なくなります。
アウトラインは、ドキュメント内のすべての見出しを、ツリー順で含むものです。
アウトラインは、たとえば目次を生成するときに、ドキュメントのアウトラインを生成するために使用されるべきです。インタラクティブな目次を作成するときは、エントリがユーザーを関連する見出しにジャンプさせるべきです。
ドキュメントに1つ以上の見出しがある場合、少なくとも1つの見出しがアウトライン内で 見出しレベル 1 を持つべきです。
見出しに続く各見出しは、leadの見出しレベル以下、同じ、または1つ上のレベルの見出しレベルを持たなければなりません。
次の例は、準拠していません:
< body >
< h1 > Apples</ h1 >
< p > Apples are fruit.</ p >
< section >
< h3 > Taste</ h3 >
< p > They taste lovely.</ p >
</ section >
</ body >
次のように書き換えると、準拠するようになります:
< body >
< h1 > Apples</ h1 >
< p > Apples are fruit.</ p >
< section >
< h2 > Taste</ h2 >
< p > They taste lovely.</ p >
</ section >
</ body >
次のマークアップフラグメントは:
< body >
< hgroup id = "document-title" >
< h1 > HTML: Living Standard</ h1 >
< p > Last Updated 12 August 2016</ p >
</ hgroup >
< p > Some intro to the document.</ p >
< h2 > Table of contents</ h2 >
< ol id = toc > ...</ ol >
< h2 > First section</ h2 >
< p > Some intro to the first section.</ p >
</ body >
...3つのドキュメント見出しを生成します:
<h1>HTML: Living Standard</h1>
<h2>Table of contents</h2>.
<h2>First section</h2>.
アウトラインのレンダリングされたビューは次のように見えるかもしれません:
まず、章やサブセクションが非常に短い本のドキュメントです:
<!DOCTYPE HTML>
< html lang = en >
< title > The Tax Book (all in one page)</ title >
< h1 > The Tax Book</ h1 >
< h2 > Earning money</ h2 >
< p > Earning money is good.</ p >
< h3 > Getting a job</ h3 >
< p > To earn money you typically need a job.</ p >
< h2 > Spending money</ h2 >
< p > Spending is what money is mainly used for.</ p >
< h3 > Cheap things</ h3 >
< p > Buying cheap things often not cost-effective.</ p >
< h3 > Expensive things</ h3 >
< p > The most expensive thing is often not the most cost-effective either.</ p >
< h2 > Investing money</ h2 >
< p > You can lend your money to other people.</ p >
< h2 > Losing money</ h2 >
< p > If you spend money or invest money, sooner or later you will lose money.
< h3 > Poor judgement</ h3 >
< p > Usually if you lose money it's because you made a mistake.</ p >
このアウトラインは次のように表示されるかもしれません:
title要素は見出しではないことに注意してください。
ドキュメントには複数のトップレベルの見出しを含めることができます:
<!DOCTYPE HTML>
< html lang = en >
< title > Alphabetic Fruit</ title >
< h1 > Apples</ h1 >
< p > Pomaceous.</ p >
< h1 > Bananas</ h1 >
< p > Edible.</ p >
< h1 > Carambola</ h1 >
< p > Star.</ p >
このドキュメントのアウトラインは次のように表示されるかもしれません:
header要素は、ドキュメントのアウトラインに影響を与えません:
<!DOCTYPE HTML>
< html lang = "en" >
< title > We're adopting a child! — Ray's blog</ title >
< h1 > Ray's blog</ h1 >
< article >
< header >
< nav >
< a href = "?t=-1d" > Yesterday</ a > ;
< a href = "?t=-7d" > Last week</ a > ;
< a href = "?t=-1m" > Last month</ a >
</ nav >
< h2 > We're adopting a child!</ h2 >
</ header >
< p > As of today, Janine and I have signed the papers to become
the proud parents of baby Diane! We've been looking forward to
this day for weeks.</ p >
</ article >
</ html >
このドキュメントのアウトラインは次のように表示されるかもしれません:
次の例は準拠していますが、見出しレベルが1である見出しがないため推奨されません:
<!DOCTYPE HTML>
< html lang = en >
< title > Alphabetic Fruit</ title >
< section >
< h2 > Apples</ h2 >
< p > Pomaceous.</ p >
</ section >
< section >
< h2 > Bananas</ h2 >
< p > Edible.</ p >
</ section >
< section >
< h2 > Carambola</ h2 >
< p > Star.</ p >
このドキュメントのアウトラインは次のように表示されるかもしれません:
次の例は準拠していますが、最初の見出しのレベルが1でないため推奨されません:
<!DOCTYPE HTML>
< html lang = en >
< title > Feathers on The Site of Encyclopedic Knowledge</ title >
< h2 > A plea from our caretakers</ h2 >
< p > Please, we beg of you, send help! We're stuck in the server room!</ p >
< h1 > Feathers</ h1 >
< p > Epidermal growths.</ p >
このドキュメントのアウトラインは次のように表示されるかもしれません:
ユーザーエージェントは、ユーザーがナビゲーションを容易に行えるように、ページのアウトラインを表示することを推奨します。これは特に、スクリーンリーダーなどの非視覚メディアにおいて重要です。
例えば、ユーザーエージェントは以下のように矢印キーをマッピングすることができます:
このセクションは規範的ではありません。
| 要素 | 目的 |
|---|---|
| 例 | |
body
| 文書の内容。 |
| |
article
| 文書、ページ、アプリケーション、またはサイト内の完全または独立した構成要素。例えば、フォーラムの投稿、雑誌や新聞の記事、ブログのエントリー、ユーザー投稿のコメント、インタラクティブウィジェットやガジェット、またはその他の独立したコンテンツアイテムが含まれる可能性があります。 |
| |
section
| 文書またはアプリケーションの一般的なセクション。この文脈では、セクションとは、通常、見出しを伴う内容のテーマ別のグループ化を指します。 |
| |
nav
| ページ内の他のページまたはページ内の部分へのリンクを含むセクション: ナビゲーションリンクが含まれるセクション。 |
| |
aside
| aside要素の周囲の内容に関連するが、それとは独立して考えられるコンテンツを含むページのセクション。このようなセクションは、印刷されたタイポグラフィでしばしばサイドバーとして表現されます。
|
| |
h1–h6
| 見出し |
| |
hgroup
| 見出しと関連コンテンツ。この要素は、1つまたは複数の 要素を含む |
| |
header
| 導入的またはナビゲーション的な支援のグループ。 |
| |
footer
| 最も近い祖先セクショニングコンテンツ要素、またはそのような祖先がない場合はbody 要素のフッター。フッターには通常、そのセクションに関する情報、著者に関するデータ、関連文書へのリンク、著作権情報などが含まれます。 |
|
このセクションは非規範的です。
sectionは他の何かの一部を構成します。articleはそれ自体が独立したものです。しかし、どちらがどちらなのかどうやって分かるのでしょうか?本当の答えは「著者の意図次第」というのがほとんどです。
例えば、「グラニースミス」という章がある本を想像してみてください。そこには「これらのジューシーな緑のリンゴはアップルパイのフィリングに最適です。」とだけ書かれているとします。それはsectionです。なぜなら、(おそらく)他の種類のリンゴに関する多くの章があるからです。
一方で、ツイートやredditのコメント、tumblrの投稿、新聞のクラシファイド広告に「グラニースミス。これらのジューシーな緑のリンゴはアップルパイのフィリングに最適です。」とだけ書かれているとしたら、それはarticleです。なぜなら、それが全体だからです。
記事へのコメントは、コメントしているarticleの一部ではないため、それ自体が独立したarticleです。
p 要素すべての現行エンジンでのサポート。
すべての現行エンジンでのサポート。
p 要素の 終了タグ は、次の要素が p 要素の後に続く場合に省略できます
address,
article,
aside, blockquote,
details, div,
dl, fieldset, figcaption,
figure,
footer, form, h1,
h2,
h3,
h4,
h5,
h6,
header, hgroup,
hr, main, menu, nav, ol,
p, pre, search, section, table,
または ul 要素、または親要素に他のコンテンツがなく、親要素が HTML 要素 であり、次の要素でない場合
a,
audio, del, ins, map, noscript,
または video 要素、または 自律型カスタム要素。
[Exposed =Window ]
interface HTMLParagraphElement : HTMLElement {
[HTMLConstructor ] constructor ();
// also has obsolete members
};
段落は通常、隣接するブロックから空白行やインデントによって物理的に分離されたテキストブロックとして視覚メディアに表されますが、スタイルシートやユーザーエージェントは、段落の区切りを異なる方法で表示することもできます。たとえば、インラインピルクロウ (¶) を使用することもできます。
次の例は、適合する HTML フラグメントです:
< p > The little kitten gently seated herself on a piece of
carpet. Later in her life, this would be referred to as the time the
cat sat on the mat.</ p >
< fieldset >
< legend > Personal information</ legend >
< p >
< label > Name: < input name = "n" ></ label >
< label >< input name = "anon" type = "checkbox" > Hide from other users</ label >
</ p >
< p >< label > Address: < textarea name = "a" ></ textarea ></ label ></ p >
</ fieldset >
< p > There was once an example from Femley,< br >
Whose markup was of dubious quality.< br >
The validator complained,< br >
So the author was pained,< br >
To move the error from the markup to the rhyming.</ p >
p 要素は、より具体的な要素がより適切である場合には使用しないでください。
次の例は技術的には正しいです:
< section >
<!-- ... -->
< p > 最終更新日: 2001-04-23</ p >
< p > 著者: fred@example.com</ p >
</ section >
ただし、次のようにマークアップする方が良いです:
< section >
<!-- ... -->
< footer > 最終更新日: 2001-04-23</ footer >
< address > 著者: fred@example.com</ address >
</ section >
または:
< section >
<!-- ... -->
< footer >
< p > 最終更新日: 2001-04-23</ p >
< address > 著者: fred@example.com</ address >
</ footer >
</ section >
リスト要素(特に ol と ul 要素)は、p
要素の子要素になることはできません。そのため、文に箇条書きリストが含まれている場合、それをどのようにマークアップするかが問題になることがあります。
例えば、この素晴らしい文には次のような箇条書きがあります
さらに以下で説明されます。
解決策は、HTML の段落が論理的な概念ではなく、構造的な概念であることを認識することです。上記の素晴らしい例では、実際にはこの仕様で定義される 5つ の段落があります: リストの前に1つ、各箇条書きに1つ、リストの後に1つ。
上記の例のマークアップは次のようになります:
< p > 例えば、この素晴らしい文には次のような箇条書きがあります</ p >
< ul >
< li > ウィザード、
< li > 光速を超える旅行、そして
< li > テレパシー、
</ ul >
< p > さらに以下で説明されます。</ p >
複数の「構造的」段落で構成される「論理的」段落を便利にスタイルしたい場合、div 要素を p 要素の代わりに使用できます。
例えば、上記の例は次のようにすることができます:
< div > 例えば、この素晴らしい文には次のような箇条書きがあります
< ul >
< li > ウィザード、
< li > 光速を超える旅行、そして
< li > テレパシー、
</ ul >
さらに以下で説明されます。</ div >
この例は依然として5つの構造的段落を持っていますが、著者は例の各部分を個別に考慮するのではなく、div 全体をスタイルすることができます。
hr
要素すべての現行エンジンでのサポート。
すべての現行エンジンでのサポート。
select 要素の子要素として。
[Exposed =Window ]
interface HTMLHRElement : HTMLElement {
[HTMLConstructor ] constructor ();
// also has obsolete members
};
hr 要素は 表します 段落レベルの主題の分割を、例えば物語のシーン変更や参考書のセクション内での話題の転換を。または、select 要素のオプションセット間の区切りを表します。
次の架空のプロジェクトマニュアルの抜粋には、セクション内でトピックを区切るために
hr 要素が使用されている2つのセクションが示されています。
< section >
< h1 > 通信</ h1 >
< p > コミュニケーションにはさまざまな方法があります。このセクションでは、プロジェクトで使用されている重要な方法のいくつかを紹介します。</ p >
< hr >
< p > 通信石はペアであるようで、神秘的な特性を持っています:</ p >
< ul >
< li > 単独で使用した場合、起動されると双方向に思考を転送できます。</ li >
< li > 他のデバイスと一緒に使用した場合、自分の意識を別の体に転送できます。</ li >
< li > 両方の石を他のデバイスと一緒に使用した場合、意識が体を交換します。</ li >
</ ul >
< hr >
< p > 無線機はメートル単位の電磁スペクトルを使用します。</ p >
< hr >
< p > 信号弾はナノメートル範囲の電磁スペクトルを使用します。</ p >
</ section >
< section >
< h1 > 食物</ h1 >
< p > プロジェクトのすべての食物は配給されています:</ p >
< dl >
< dt > じゃがいも</ dt >
< dd > 1日2個</ dd >
< dt > スープ</ dt >
< dd > 1日1杯</ dd >
</ dl >
< hr >
< p > 料理はシェフが決められたローテーションで行います。</ p >
</ section >
セクション間に hr 要素を配置する必要はありません、
なぜなら section 要素や
h1
要素が主題の変化を意味するからです。
Peter F. Hamilton の Pandora's Star
からの次の抜粋には、シーン変更の前の2つの段落とその後の段落が示されています。印刷された本では、シーン変更は2番目と3番目の段落の間に1つの孤立した中心に配置された星で表されていますが、ここでは hr 要素を使用して表されています。
< p > Dudley was ninety-two, in his second life, and fast approaching
time for another rejuvenation. Despite his body having the physical
age of a standard fifty-year-old, the prospect of a long degrading
campaign within academia was one he regarded with dread. For a
supposedly advanced civilization, the Intersolar Commonwealth could be
appallingly backward at times, not to mention cruel.</ p >
< p >< i > Maybe it won't be that bad</ i > , he told himself. The lie was
comforting enough to get him through the rest of the night's
shift.</ p >
< hr >
< p > The Carlton AllLander drove Dudley home just after dawn. Like the
astronomer, the vehicle was old and worn, but perfectly capable of
doing its job. It had a cheap diesel engine, common enough on a
semi-frontier world like Gralmond, although its drive array was a
thoroughly modern photoneural processor. With its high suspension and
deep-tread tyres it could plough along the dirt track to the
observatory in all weather and seasons, including the metre-deep snow
of Gralmond's winters.</ p >
pre
要素すべての現行エンジンでのサポート。
すべての現行エンジンでのサポート。
[Exposed =Window ]
interface HTMLPreElement : HTMLElement {
[HTMLConstructor ] constructor ();
// also has obsolete members
};
pre
要素は、整形済みテキストのブロックを表し、構造が要素ではなく印刷上の規則によって表されます。
HTML 構文では、pre 要素の開始タグに続く先頭の改行文字が取り除かれます。
pre 要素が使用されるケースの例:
著者は、フォーマットが失われた場合に整形済みテキストがどのように表示されるかを考慮することをお勧めします。これは、音声合成装置や点字ディスプレイなどのユーザーに当てはまります。ASCII アートのような場合には、テキストの説明など、より普遍的にアクセス可能な代替の表現が読者にとって望ましいでしょう。
コンピュータコードのブロックを表すには、pre 要素を code
要素と共に使用することができます。また、コンピュータ出力のブロックを表すには、pre 要素を samp 要素と共に使用することができます。同様に、kbd 要素を pre
要素内で使用して、ユーザーが入力するテキストを示すことができます。
この要素は双方向アルゴリズムに関するレンダリング要件を持ちます。
次のスニペットでは、コンピュータコードのサンプルが表示されています。
< p > これは < code > Panel</ code > コンストラクタです:</ p >
< pre >< code > function Panel(element, canClose, closeHandler) {
this.element = element;
this.canClose = canClose;
this.closeHandler = function () { if (closeHandler) closeHandler() };
}</ code ></ pre >
次のスニペットでは、samp と kbd 要素が pre 要素内に混在して、Zork I
のセッションが表示されています。
< pre >< samp > You are in an open field west of a big white house with a boarded
front door.
There is a small mailbox here.
></ samp > < kbd > open mailbox</ kbd >
< samp > Opening the mailbox reveals:
A leaflet.
></ samp ></ pre >
次の例では、pre
要素を使用してその異常なフォーマットを保持している現代詩が示されています。このフォーマットは詩自体の本質的な部分を形成します。
< pre > maxling
it is with a heart
heavy
that i admit loss of a feline
so loved
a friend lost to the
unknown
(night)
~cdr 11dec07</ pre >
blockquote 要素
すべての現行エンジンでのサポート。
すべての現行エンジンでのサポート。
cite —
引用の出典または編集に関する追加情報へのリンク
[Exposed =Window ]
interface HTMLQuoteElement : HTMLElement {
[HTMLConstructor ] constructor ();
[CEReactions ] attribute USVString cite ;
};
HTMLQuoteElement
インターフェイスは、q 要素にも使用されます。
blockquote
要素は、他のソースから引用されたセクションを表します。
blockquote
内のコンテンツは、他のソースからの引用である必要があり、そのアドレスがある場合は cite 属性で引用することができます。
cite
属性が存在する場合、それは 有効な URL (スペースで囲まれている可能性あり)
でなければなりません。対応する引用リンクを取得するためには、その属性の値は要素の ノードドキュメント に対して 解析
されなければなりません。ユーザーエージェントは、そのような引用リンクをユーザーがたどることを許可する場合がありますが、これらは主にプライベートな使用(例:
サイトの引用の使用に関する統計を収集するサーバー側のスクリプトなど)を目的としており、読者のためではありません。
blockquote
の内容は、省略されるか、テキストの言語の慣習に従って文脈が追加されることがあります。
例えば、英語では伝統的に角括弧を使用します。次の文章を含むページを考えてみましょう。「Jane はクラッカーを食べた。そして彼女はリンゴと魚が好きだと言った。」これを次のように引用できます:
< blockquote >
< p > [Jane] then said she liked [...] fish.</ p >
</ blockquote >
引用の出典がある場合は、blockquote
要素の外に配置する必要があります。
例えば、ここでは引用の出典が引用の後の段落に与えられています:
< blockquote >
< p > I contend that we are both atheists. I just believe in one fewer
god than you do. When you understand why you dismiss all the other
possible gods, you will understand why I dismiss yours.</ p >
</ blockquote >
< p > — Stephen Roberts</ p >
以下の他の例は、出典を示す他の方法を示しています。
cite IDL 属性は、要素の
cite コンテンツ属性を 反映する必要があります。
ここでは、blockquote
要素が figure 要素とその
figcaption
と共に使用され、引用をその出典に明確に関連付けています(これは引用の一部ではないため、blockquote
内には属しません)。
< figure >
< blockquote >
< p > The truth may be puzzling. It may take some work to grapple with.
It may be counterintuitive. It may contradict deeply held
prejudices. It may not be consonant with what we desperately want to
be true. But our preferences do not determine what's true. We have a
method, and that method helps us to reach not absolute truth, only
asymptotic approaches to the truth — never there, just closer
and closer, always finding vast new oceans of undiscovered
possibilities. Cleverly designed experiments are the key.</ p >
</ blockquote >
< figcaption > Carl Sagan, in "< cite > Wonder and Skepticism</ cite > ", from
the < cite > Skeptical Inquirer</ cite > Volume 19, Issue 1 (January-February
1995)</ figcaption >
</ figure >
次の例では、cite と blockquote
の併用が示されています。
< p > His next piece was the aptly named < cite > Sonnet 130</ cite > :</ p >
< blockquote cite = "https://quotes.example.org/s/sonnet130.html" >
< p > My mistress' eyes are nothing like the sun,< br >
Coral is far more red, than her lips red,< br >
...
この例では、フォーラムの投稿が blockquote
を使用してユーザーがどの投稿に返信しているかを示す方法を示しています。article
要素はスレッド化をマークアップするために各投稿に使用されています。
< article >
< h1 >< a href = "https://bacon.example.com/?blog=109431" > Bacon on a crowbar</ a ></ h1 >
< article >
< header >< strong > t3yw</ strong > 12 points 1 hour ago</ header >
< p > I bet a narwhal would love that.</ p >
< footer >< a href = "?pid=29578" > permalink</ a ></ footer >
< article >
< header >< strong > greg</ strong > 8 points 1 hour ago</ header >
< blockquote >< p > I bet a narwhal would love that.</ p ></ blockquote >
< p > Dude narwhals don't eat bacon.</ p >
< footer >< a href = "?pid=29579" > permalink</ a ></ footer >
< article >
< header >< strong > t3yw</ strong > 15 points 1 hour ago</ header >
< blockquote >
< blockquote >< p > I bet a narwhal would love that.</ p ></ blockquote >
< p > Dude narwhals don't eat bacon.</ p >
</ blockquote >
< p > Next thing you'll be saying they don't get capes and wizard
hats either!</ p >
< footer >< a href = "?pid=29580" > permalink</ a ></ footer >
< article >
< article >
< header >< strong > boing</ strong > -5 points 1 hour ago</ header >
< p > narwhals are worse than ceiling cat</ p >
< footer >< a href = "?pid=29581" > permalink</ a ></ footer >
</ article >
</ article >
</ article >
</ article >
< article >
< header >< strong > fred</ strong > 1 points 23 minutes ago</ header >
< blockquote >< p > I bet a narwhal would love that.</ p ></ blockquote >
< p > I bet they'd love to peel a banana too.</ p >
< footer >< a href = "?pid=29582" > permalink</ a ></ footer >
</ article >
</ article >
</ article >
次の例は、blockquote
を使用した短いスニペットの使用を示しており、p 要素を
blockquote
要素内に使用する必要がないことを示しています:
< p > He began his list of "lessons" with the following:</ p >
< blockquote > One should never assume that his side of
the issue will be recognized, let alone that it will
be conceded to have merits.</ blockquote >
< p > He continued with a number of similar points, ending with:</ p >
< blockquote > Finally, one should be prepared for the threat
of breakdown in negotiations at any given moment and not
be cowed by the possibility.</ blockquote >
< p > We shall now discuss these points...
会話を表現する方法の例は後のセクションに示されています。この目的のために cite と blockquote
要素を使用するのは適切ではありません。
ol 要素
すべての現行エンジンでサポートされています。
すべての現行エンジンでサポートされています。
li要素が含まれている場合: 実質的コンテンツ。
liおよびスクリプトサポート要素。
reversed — リストを逆順に番号付け
start — リストの開始値
type — リストマーカーの種類
[Exposed =Window ]
interface HTMLOListElement : HTMLElement {
[HTMLConstructor ] constructor ();
[CEReactions ] attribute boolean reversed ;
[CEReactions ] attribute long start ;
[CEReactions ] attribute DOMString type ;
// 廃止されたメンバーも含まれます
};
ol要素は、アイテムが意図的に順序付けされており、その順序を変更するとドキュメントの意味が変わるようなリストを表します。
リストのアイテムは、li要素の子ノードであり、ol要素内でツリー順に配置されます。
すべての最新のエンジンでサポートされています。
reversed属性はブール属性です。存在する場合、リストが降順(...、3、2、1)であることを示します。属性が省略されている場合、リストは昇順(1、2、3、...)になります。
start属性は、存在する場合、有効な整数でなければなりません。この属性はリストの開始値を決定するために使用されます。
ol要素には、次のようにして決定される整数の開始値があります。
parsedを、属性値を整数として解析した結果とする。
parsedがエラーでない場合、parsedを返す。
もしol要素にreversed属性がある場合、所有されているli要素の数を返す。
1を返す。
type属性は、リスト内のマーカーの種類を指定するために使用されます。これは、アイテムがその番号/文字によって参照されるなどの場合に重要です。属性が指定されている場合、その値は同一である必要があり、次の表の最初のセルの1つに与えられた文字のいずれかでなければなりません。type属性は、表の最初のセルに一致する行の2番目の列に与えられた状態を表します。セルが一致しない場合、または属性が省略された場合、属性は10進数状態を表します。
| キーワード | 状態 | 説明 | 値1-3および3999-4001の例 | |||||||
|---|---|---|---|---|---|---|---|---|---|---|
1(U+0031)
| 10進数 | 10進数 | 1. | 2. | 3. | ... | 3999. | 4000. | 4001. | ... |
a (U+0061)
| 小文字アルファベット | 小文字ラテンアルファベット | a. | b. | c. | ... | ewu. | ewv. | eww. | ... |
A (U+0041)
| 大文字アルファベット | 大文字ラテンアルファベット | A. | B. | C. | ... | EWU. | EWV. | EWW. | ... |
i (U+0069)
| 小文字ローマ数字 | 小文字ローマ数字 | i. | ii. | iii. | ... | mmmcmxcix. | i̅v̅. | i̅v̅i. | ... |
I (U+0049)
| 大文字ローマ数字 | 大文字ローマ数字 | I. | II. | III. | ... | MMMCMXCIX. | I̅V̅. | I̅V̅I. | ... |
ユーザーエージェントは、type属性の状態に一致する形式でリストのアイテムをレンダリングする必要があります。値が0以下の数値の場合、type属性に関係なく、常に10進数システムを使用する必要があります。
CSSユーザーエージェントの場合、この属性の'list-style-type'CSSプロパティへのマッピングは、レンダリングセクションで与えられます(マッピングは簡単です:上記の状態は対応するCSS値と同じ名前を持っています)。
この属性を実装するために使用されるデフォルトのCSSリストスタイルを再定義することが可能です。これにより、リストアイテムの表示方法が影響を受けます。
reversedおよびtypeIDL属性は、それぞれの同名のコンテンツ属性を反映する必要があります。
startIDL属性は、同名のコンテンツ属性を反映し、デフォルト値として1を持つ必要があります。
これにより、startIDL属性は、属性が省略されていてreversed属性が指定されている場合、必ずしもリストの開始値と一致するわけではありません。
次のマークアップは、順序が重要であり、ol要素が適切であるリストを示しています。このリストを、ul要素を使用した同様のアイテムの例と比較して、ul要素を使用する例を参照してください。
< p > I have lived in the following countries (given in the order of when I first lived there):</ p >
< ol >
< li > Switzerland
< li > United Kingdom
< li > United States
< li > Norway
</ ol >
リストの順序を変更すると、ドキュメントの意味がどのように変わるかに注目してください。次の例では、最初の2つのアイテムの相対的な順序を変更することで、著者の出生地が変わりました。
< p > I have lived in the following countries (given in the order of when I first lived there):</ p >
< ol >
< li > United Kingdom
< li > Switzerland
< li > United States
< li > Norway
</ ol >
ul
要素すべての現在のエンジンでサポートされています。
すべての現在のエンジンでサポートされています。
li 要素が含まれている場合:明示的コンテンツ。
li および スクリプトサポート要素。
[Exposed =Window ]
interface HTMLUListElement : HTMLElement {
[HTMLConstructor ] constructor ();
// 廃止されたメンバーもあります
};
ul
要素は、アイテムの順序が重要ではないリスト、つまり順序を変更してもドキュメントの意味が大幅に変わらないリストを表します。
リストのアイテムは、li 要素の子ノードであり、ul 要素の子ノードです。
次のマークアップは、順序が重要でなく、ul
要素が適切であるリストを示しています。このリストを、同じアイテムを使用した ol セクションの同等のリストと比較してみてください。
< p > I have lived in the following countries:</ p >
< ul >
< li > Norway
< li > Switzerland
< li > United Kingdom
< li > United States
</ ul >
リストの順序を変更してもドキュメントの意味が変わらないことに注意してください。上記のスニペットではアイテムがアルファベット順に並んでいますが、以下のスニペットでは 2007 年の現在の口座残高に基づいて並んでおり、ドキュメントの意味がまったく変わりません:
< p > I have lived in the following countries:</ p >
< ul >
< li > Switzerland
< li > Norway
< li > United Kingdom
< li > United States
</ ul >
menu
要素
すべての現在のエンジンでサポートされています。
すべての現在のエンジンでサポートされています。
li
要素が含まれている場合:明示的コンテンツ。
li および スクリプトサポート要素。
[Exposed =Window ]
interface HTMLMenuElement : HTMLElement {
[HTMLConstructor ] constructor ();
// 廃止されたメンバーもあります
};
menu 要素は、項目の順序付けされていないリスト(li
要素で表される)の形で、その内容で構成されるツールバーを表します。それぞれの項目は、ユーザーが実行または起動できるコマンドを表します。
menu
要素は、コマンドの順序付けされていないリスト(「ツールバー」)を表現するための、ul のセマンティックな代替にすぎません。
この例では、テキスト編集アプリケーションが menu
要素を使用して、一連の編集コマンドを提供しています:
< menu >
< li >< button onclick = "copy()" >< img src = "copy.svg" alt = "Copy" ></ button ></ li >
< li >< button onclick = "cut()" >< img src = "cut.svg" alt = "Cut" ></ button ></ li >
< li >< button onclick = "paste()" >< img src = "paste.svg" alt = "Paste" ></ button ></ li >
</ menu >
従来のツールバーメニューのように見せるスタイリングは、アプリケーションの役割です。
li
要素全ての現行エンジンでのサポート。
全ての現行エンジンでのサポート。
ol 要素内。
ul 要素内。
menu 要素内。
li 要素が続くか、親要素にこれ以上コンテンツがない場合、終了タグ を省略できます。
ul または menu 要素の子でない場合: value — リストアイテムの 序数。
[Exposed =Window ]
interface HTMLLIElement : HTMLElement {
[HTMLConstructor ] constructor ();
[CEReactions ] attribute long value ;
// 廃止されたメンバーも含まれます
};
li 要素は、リスト項目を表します。親要素が
ol、ul、または menu
要素である場合、リストアイテムはこれらの要素で定義される親要素のリストの項目となります。それ以外の場合、リストアイテムには他の li 要素とのリスト関連の関係は定義されていません。
属性 value が存在する場合、有効な整数でなければなりません。これは、リストアイテムの 序数 を決定するために使用されます。li の リストオーナー が ol 要素である場合。
任意の要素で、計算された値 の 'display' が 'list-item' であるものには、 以下の方法で決定される リストオーナー がいます。
その要素が レンダリングされていない 場合、null を返します。その要素には リストオーナー がありません。
その要素の親要素を ancestor とします。
その要素が ol、
ul、または menu
の祖先を持つ場合、ancestor を最も近いそのような祖先要素に設定します。
ancestor の最も近い包括的な祖先で、CSS ボックス を生成する要素を返します。
特定の リストオーナー owner が所有する各要素の 序数 を決定するために、次の手順を実行します:
i を 1 に設定します。
owner が ol
要素である場合、numbering を
owner の 開始値 に設定します。
それ以外の場合、numbering を 1 に設定します。
ループ: i が オーナーが所有するリストアイテム の数を超える場合、終了します。すべての 所有されたリストアイテム に 序数 が割り当てられました。
item が li
要素であり、value
属性を持つ場合、次の手順を実行します。
属性の値を整数として解析する結果を parsed に設定します。
parsed がエラーでない場合、numbering を parsed に設定します。
item の 序数 は numbering です。
owner が ol
要素であり、owner が 逆順
属性を持っている場合、numbering を 1 減らします。
それ以外の場合、numbering を 1 増やします。
i を 1 増やします。
ループ ラベルの付いたステップに戻ります。
value IDL
属性は value コンテンツ属性の値を反映しなければなりません。
要素の value IDL 属性は、その序数 に直接対応するものではなく、単にコンテンツ属性を反映します。例えば、このリストの場合:
< ol >
< li > アイテム 1
< li value = "3" > アイテム 3
< li > アイテム 4
</ ol >
序数は 1、3、4 ですが、value IDL 属性の取得時の戻り値は
0、3、0 です。
次の例では、トップテン映画が(逆順で)リストされています。figure 要素とその figcaption
要素を使用して、リストにタイトルを付ける方法に注目してください。
< figure >
< figcaption > 史上最高の映画トップ 10</ figcaption >
< ol >
< li value = "10" >< cite > ジョシーとプッシーキャッツ</ cite > 、2001</ li >
< li value = "9" >< cite lang = "sh" > Црна мачка, бели мачор</ cite > 、1998</ li >
< li value = "8" >< cite > バグズ・ライフ</ cite > 、1998</ li >
< li value = "7" >< cite > トイ・ストーリー</ cite > 、1995</ li > 、
< li value = "6" >< cite > モンスターズ・インク</ cite > 、2001</ li > 、
< li value = "5" >< cite > カーズ</ cite > 、2006</ li > 、
< li value = "4" >< cite > トイ・ストーリー 2</ cite > 、1999</ li > 、
< li value = "3" >< cite > ファインディング・ニモ</ cite > 、2003</ li > 、
< li value = "2" >< cite > Mr.インクレディブル</ cite > 、2004</ li > 、
< li value = "1" >< cite > レミーのおいしいレストラン</ cite > 、2007</ li > 、
</ ol >
</ figure >
また、逆順 属性を ol
要素に使用することで、以下のようにマークアップすることもできます。
< figure >
< figcaption > 史上最高の映画トップ 10</ figcaption >
< ol reversed >
< li >< cite > ジョシーとプッシーキャッツ</ cite > 、2001</ li >
< li >< cite lang = "sh" > Црна мачка, бели мачор</ cite > 、1998</ li >
< li >< cite > バグズ・ライフ</ cite > 、1998</ li >
< li >< cite > トイ・ストーリー</ cite > 、1995</ li >
< li >< cite > モンスターズ・インク</ cite > 、2001</ li >
< li >< cite > カーズ</ cite > 、2006</ li >
< li >< cite > トイ・ストーリー 2</ cite > 、1999</ li >
< li >< cite > ファインディング・ニモ</ cite > 、2003</ li >
< li >< cite > Mr.インクレディブル</ cite > 、2004</ li >
< li >< cite > レミーのおいしいレストラン</ cite > 、2007</ li >
</ ol >
</ figure >
h1
要素などの見出し要素を li
要素内に含めることは適合していますが、著者が意図したセマンティクスを伝えていない可能性が高いです。見出しは新しいセクションの始まりを示すため、リスト内の見出しは暗黙的にリストを複数のセクションに分割します。
dl
要素すべての現行エンジンでのサポート。
すべての現行エンジンでのサポート。
dt 要素のグループと、1 つ以上の
dd 要素のグループ。これらは、スクリプトサポート要素
と混在する場合があります。
div 要素と、スクリプトサポート要素
が混在する場合があります。
[Exposed =Window ]
interface HTMLDListElement : HTMLElement {
[HTMLConstructor ] constructor ();
// 廃止されたメンバーも含まれます
};
dl 要素は、0 個以上の名前と値のペア(記述リスト)からなる関連リストを表します。名前と値のペアは、1 つ以上の名前(dt 要素、子要素としての div 要素を含む場合があります)と、それに続く 1
つ以上の値(dd 要素、子要素としての div
要素を含む場合があります)で構成されます。他のノードは無視され、dt
要素と dd 要素の子要素、および dt 要素と dd 要素が div 要素の子要素である場合にのみ考慮されます。1 つの dl 要素内には、1 つの名前に対して 1 つ以上の dt 要素が含まれてはなりません。
名前と値のペアは、用語と定義、メタデータのトピックと値、質問と回答、またはその他の名前と値のデータのグループである可能性があります。
グループ内の値は代替案です。同じ値の一部を構成する複数の段落は、すべて同じ dd 要素内に記載する必要があります。
グループのリスト、および各グループ内の名前と値の順序は、重要である場合があります。
グループに マイクロデータ 属性や他の グローバル属性 を適用して注釈を付けたり、単にスタイリングの目的で使用したりするために、dl 要素内の各グループを div 要素でラップすることができます。これにより、dl 要素のセマンティクスは変わりません。
dl 要素 dl
の名前と値のペアは、次のアルゴリズムを使用して決定されます。名前と値のペアには名前(dt 要素のリスト、初期は空)と値(dd 要素のリスト、初期は空)があります。
groups を名前と値のペアの空のリストに設定します。
current を新しい名前と値のペアに設定します。
seenDd を false に設定します。
child を dl の 最初の子要素 に設定します。
grandchild を null に設定します。
child が null でない間:
child が div
要素である場合、次の手順を実行します:
grandchild を child の 最初の子要素 に設定します。
grandchild が null でない間:
プロセス
dt または dd を grandchild に対して実行します。
grandchild を grandchild の 次の兄弟 に設定します。
それ以外の場合、プロセス dt
または dd を child に対して実行します。
child を child の 次の兄弟 に設定します。
current が空でない場合、current を groups に追加します。
groups を返します。
ノード node に対して dt または dd をプロセスする
ための処理を行うことは、次の手順を意味します:
groups、current、および seenDd を、これらの手順を呼び出したアルゴリズム内の同じ名前の変数と同じものに設定します。
node が dt
要素である場合、次の手順を実行します。
seenDd が true である場合、current を groups に追加し、current を新しい名前と値のペアに設定し、seenDd を false に設定します。
node を current の名前に追加します。
それ以外の場合、node が dd
要素である場合、node を current の値に追加し、seenDd を true に設定します。
名前と値のペアに空のリストが名前または値として含まれている場合、しばしば dd 要素が dt
要素の代わりに誤って使用されていることが原因です。適合性チェッカーはそのようなミスを検出し、著者に適切なマークアップの使用方法を助言することができるかもしれません。
次の例では、1 つのエントリ(「著者」)が 2 つの値(「ジョン」と「ルーク」)にリンクされています。
< dl >
< dt > 著者
< dd > ジョン
< dd > ルーク
< dt > 編集者
< dd > フランク
</ dl >
次の例では、1 つの定義が 2 つの用語にリンクされています。
< dl >
< dt lang = "en-US" > < dfn > color</ dfn > </ dt >
< dt lang = "en-GB" > < dfn > colour</ dfn > </ dt >
< dd > 人間の場合、視覚の細かな構造が 3 つの異なるフィルター分析を識別する能力に起因する感覚です。</ dd >
</ dl >
次の例は、メタデータの一種をマークアップするために dl
要素を使用する例です。例の最後では、1 つのグループに 2 つのメタデータラベル(「著者」と「編集者」)と 2
つの値(「ロバート・ロスマン」と「ダニエル・ジャクソン」)が含まれています。この例では、スタイリングを補助するために div 要素も使用されています。
< dl >
< div >
< dt > 最終更新日時 </ dt >
< dd > 2004-12-23T23:33Z </ dd >
</ div >
< div >
< dt > 推奨更新間隔 </ dt >
< dd > 60s </ dd >
</ div >
< div >
< dt > 著者 </ dt >
< dt > 編集者 </ dt >
< dd > ロバート・ロスマン </ dd >
< dd > ダニエル・ジャクソン </ dd >
</ div >
</ dl >
次の例では、手順を提示するために dl 要素が使用されています。
ここでは手順の順序が重要です(他の例では、ブロックの順序は重要ではありませんでした)。
< p > 次のようにして勝利ポイントを決定します(最初に一致するケースを使用します):</ p >
< dl >
< dt > ちょうど5つの金貨がある場合 </ dt >
< dd > 5つの勝利ポイントを獲得します </ dd >
< dt > 1つ以上の金貨があり、1つ以上の銀貨がある場合 </ dt >
< dd > 2つの勝利ポイントを獲得します </ dd >
</ dt > 1つ以上の銀貨がある場合 </ dt >
< dd > 1つの勝利ポイントを獲得します </ dd >
</ dt > その他の場合 </ dt >
< dd > 勝利ポイントは獲得できません </ dd >
</ dl >
次のスニペットでは、dl
要素が用語集として使用されています。定義されている単語を示すための dfn の使用に注目してください。
< dl >
< dt >< dfn > アパートメント</ dfn > 、n.</ dt >
< dd > 1つ以上のスレッドと1つ以上のCOMオブジェクトをグループ化する実行コンテキスト。</ dd >
< dt >< dfn > フラット</ dfn > 、n.</ dt >
< dd > 空気の抜けたタイヤ。</ dd >
< dt >< dfn > ホーム</ dfn > 、n.</ dt >
< dd > ユーザーのログインディレクトリ。</ dd >
</ dl >
この例では、マイクロデータ 属性を使用して、dl 要素と div
要素を使用してフランスのレストランのアイスクリームデザートに注釈を付けています。
< dl >
< div itemscope itemtype = "http://schema.org/Product" >
< dt itemprop = "name" > カフェまたはチョコレート・リエジョワ
< dd itemprop = "offers" itemscope itemtype = "http://schema.org/Offer" >
< span itemprop = "price" > 3.50</ span >
< data itemprop = "priceCurrency" value = "EUR" > €</ data >
< dd itemprop = "description" >
2つのカフェまたはチョコレートボール、1つのバニラボール、カフェまたはチョコレートソース、ホイップクリーム
</ div >
< div itemscope itemtype = "http://schema.org/Product" >
< dt itemprop = "name" > アメリカン
< dd itemprop = "offers" itemscope itemtype = "http://schema.org/Offer" >
< span itemprop = "price" > 3.50</ span >
< data itemprop = "priceCurrency" value = "EUR" > €</ data >
< dd itemprop = "description" >
1つのクレームブリュレボール、1つのバニラボール、1つのキャラメルボール、ホイップクリーム
</ div >
</ dl >
div 要素がない場合、次のように itemref 属性を使用して、dd 要素のデータをアイテムとリンクする必要があります。
< dl >
< dt itemscope itemtype = "http://schema.org/Product" itemref = "1-offer 1-description" >
< span itemprop = "name" > カフェまたはチョコレート・リエジョワ</ span >
< dd id = "1-offer" itemprop = "offers" itemscope itemtype = "http://schema.org/Offer" >
< span itemprop = "price" > 3.50</ span >
</ data itemprop = "priceCurrency" value = "EUR" > €</ data >
</ dd id = "1-description" itemprop = "description" >
2つのカフェまたはチョコレートボール、1つのバニラボール、カフェまたはチョコレートソース、ホイップクリーム
</ dt itemscope itemtype = "http://schema.org/Product" itemref = "2-offer 2-description" >
< span itemprop = "name" > アメリカン</ span >
< dd id = "2-offer" itemprop = "offers" itemscope itemtype = "http://schema.org/Offer" >
< span itemprop = "price" > 3.50</ span >
</ data itemprop = "priceCurrency" value = "EUR" > €</ data >
</ dd id = "2-description" itemprop = "description" >
1つのクレームブリュレボール、1つのバニラボール、1つのキャラメルボール、ホイップクリーム
</ dl >
dl
要素は、対話をマークアップするためには適していません。対話のマークアップ方法の例をご覧ください。
dt要素すべての現在のエンジンでサポートされています。
dl要素内のddまたはdt要素の前。
dl要素の子であるdiv要素内のddまたはdt要素の前。
header、footer、セクショニングコンテンツまたは見出しコンテンツの子孫を持たないこと。
dt要素の終了タグは、次に別のdt要素またはdd要素が続く場合に省略可能です。
HTMLElementを使用。
dt要素は、説明リスト(dl要素)の用語説明グループの用語または名前部分を表します。
dt要素自体は、dl要素内で使用されるとき、その内容が定義されている用語であることを示しませんが、これはdfn要素を使用して示すことができます。
次の例は、質問にはdt要素を、回答にはdd要素を使用してFAQをマークアップしたものです。
< article >
< h1 > FAQ</ h1 >
< dl >
< dt > What do we want?</ dt >
< dd > Our data.</ dd >
< dt > When do we want it?</ dt >
< dd > Now.</ dd >
< dt > Where is it?</ dt >
< dd > We are not sure.</ dd >
</ dl >
</ article >
dd要素すべての現在のエンジンでサポートされています。
dl要素内のdtまたはdd要素の後。
dl要素の子であるdiv要素内のdtまたはdd要素の後。
dd要素の終了タグは、次に別のdd要素またはdt要素が続く場合、または親要素にこれ以上コンテンツがない場合に省略可能です。
HTMLElementを使用。
dd要素は、説明リスト(dl要素)の用語説明グループの説明、定義、または値の部分を表します。
dlは、辞書のように語彙リストを定義するために使用できます。次の例では、dtとdfnで与えられた各エントリに、さまざまな定義の部分を示すいくつかのddがあります。
< dl >
< dt >< dfn > happiness</ dfn ></ dt >
< dd class = "pronunciation" > /ˈhæpinəs/</ dd >
< dd class = "part-of-speech" >< i >< abbr > n.</ abbr ></ i ></ dd >
< dd > The state of being happy.</ dd >
< dd > Good fortune; success. < q > Oh < b > happiness</ b > ! It worked!</ q ></ dd >
< dt >< dfn > rejoice</ dfn ></ dt >
< dd class = "pronunciation" > /rɪˈdʒɔɪs/</ dd >
< dd >< i class = "part-of-speech" >< abbr > v.intr.</ abbr ></ i > To be delighted oneself.</ dd >
< dd >< i class = "part-of-speech" >< abbr > v.tr.</ abbr ></ i > To cause one to be delighted.</ dd >
</ dl >
figure要素すべての現在のエンジンでサポートされています。
figcaption要素の後にフローコンテンツ。
figcaption要素。
HTMLElementを使用。
figure要素は、オプションでキャプションを付けたフローコンテンツを表します。これは独立した内容で(完全な文のように)、通常はドキュメントの主要な流れから単一の単位として参照されます。
この文脈で「独立した」とは、必ずしも独立した存在を意味するわけではありません。たとえば、段落内の各文は独立していますが、文の一部である画像はfigureに適していませんが、画像で構成された完全な文は適しているといえます。
この要素は、イラスト、図、写真、コードリストなどを注釈するために使用できます。
figureがキャプション(たとえば図の番号)によって識別され、ドキュメントの主要なコンテンツから参照されている場合、こうしたコンテンツをページの横、専用ページ、または付録に移動させても、ドキュメントの流れに影響を与えずに済むようになります。
figure要素が相対的な位置(たとえば「上の写真」や「次の図が示すように」など)で参照されている場合、そのfigureを移動させるとページの意味が乱れてしまいます。著者は、ページが簡単に再スタイル化されてもページの意味が影響を受けないように、相対参照の代わりにラベルを使用してfigureを参照することを検討することをお勧めします。
最初のfigcaption要素の子要素がある場合は、そのfigure要素の内容のキャプションを表します。子figcaption要素がない場合、キャプションは存在しません。
figure要素の内容は、周囲の流れの一部です。たとえば、画像共有サイトで写真を表示することがページの目的である場合、figureとfigcaption要素を使用して、そのfigureにキャプションを明示的に提供できます。周囲の流れにわずかに関連するコンテンツや別の目的を果たすコンテンツの場合は、aside要素を使用するべきです(figureを包むこともできます)。たとえば、記事からのコンテンツを繰り返す引用が、読者を引き付けるためや重要なトピックを強調するために、figureよりもasideに適しているでしょう。
この例では、コードリストをマークアップするためにfigure要素を使用しています。
< p > < a href = "#l4" > リスト4</ a > で、主なコアインターフェースAPI宣言を確認できます。</ p >
< figure id = "l4" >
< figcaption > リスト4. 主なコアインターフェースAPI宣言。</ figcaption >
< pre >< code > interface PrimaryCore {
boolean verifyDataLine();
undefined sendData(sequence< byte> data);
undefined initSelfDestruct();
}</ code ></ pre >
</ figure >
< p > APIはUTF-8を使用するように設計されています。</ p >
ここでは、ページの主要なコンテンツとしてマークアップされたfigure要素を使用して、写真をマークアップしています(ギャラリーのように)。
<!DOCTYPE HTML>
< html lang = "en" >
< title > Bubbles at work — My Gallery™</ title >
< figure >
< img src = "bubbles-work.jpeg"
alt = "Bubbles, sitting in his office chair, works on his"
latest project intently." >
< figcaption > Bubbles at work</ figcaption >
</ figure >
< nav >< a href = "19414.html" > 前</ a > — < a href = "19416.html" > 次</ a ></ nav >
この例では、figureではない画像と、figureである画像とビデオを示しています。最初の画像は、この例の2番目の文の一部であり、独立したユニットではないため、figureには不適切です。
< h2 > Malinko's comics</ h2 >
< p > この事件は、ある種の「知的財産」侵害に関するもので、漫画に関連しています(エキシビットAを参照)。訴訟は次の言葉で終わるトレーラーが公開された後に始まりました:
< blockquote >
< img src = "promblem-packed-action.png" alt = "ROUGH COPY! Promblem-Packed Action!" >
</ blockquote >
< p > ...が放送されました。弁護士が大きなノートを持って先制攻撃を開始しました。このトレーラーの完全なコピーはエキシビットBに含まれています。
< figure >
< img src = "ex-a.png" alt = "汚れた紙に描かれた2つの落書きのようなもの。" >
< figcaption > エキシビットA. 主張された< cite > 粗いコピー</ cite > の漫画。</ figcaption >
</ figure >
< figure >
< video src = "ex-b.mov" ></ video >
< figcaption > エキシビットB. < cite > 粗いコピー</ cite > のトレーラー。</ figcaption >
</ figure >
< p > 訴訟は法廷外で解決されました。
この例では、詩の一部をfigureを使用してマークアップしています。
< figure >
< p > 'Twas brillig, and the slithy toves< br >
Did gyre and gimble in the wabe;< br >
All mimsy were the borogoves,< br >
And the mome raths outgrabe.</ p >
< figcaption >< cite > ジャバウォックィ</ cite > (第1詩)。ルイス・キャロル、1832-98</ figcaption >
</ figure >
この例では、城に関するはるかに大きな作品の一部である可能性がある部分において、ネストされたfigure要素を使用して、グループキャプションと、グループ内の各figureに対する個別のキャプションの両方を提供しています:
< figure >
< figcaption > 時代を超えての城: 1423年、1858年、そして1999年の順に。</ figcaption >
< figure >
< figcaption > エッチング。匿名、約1423年。</ figcaption >
< img src = "castle1423.jpeg" alt = "城には1つの塔があり、高い壁に囲まれています。" >
</ figure >
< figure >
< figcaption > 油絵。マリア・トウル、1858年。</ figcaption >
< img src = "castle1858.jpeg" alt = "城には現在2つの塔と2つの壁があります。" >
</ figure >
< figure >
< figcaption > フィルム写真。ピーター・ジャンクル、1999年。</ figcaption >
< img src = "castle1999.jpeg" alt = "城は廃墟となり、元の塔だけが一体化しています。" >
</ figure >
</ figure >
前の例は、ネストされたfigure/figcaptionペアの代わりにtitle属性を使用して、より簡潔に書くことができます:
< figure >
< img src = "castle1423.jpeg" title = "エッチング。匿名、約1423年。" alt = "城には1つの塔があり、高い壁に囲まれています。" >
< img src = "castle1858.jpeg" title = "油絵。マリア・トウル、1858年。" alt = "城には現在2つの塔と2つの壁があります。" >
< img src = "castle1999.jpeg" title = "フィルム写真。ピーター・ジャンクル、1999年。" alt = "城は廃墟となり、元の塔だけが一体化しています。" >
< figcaption > 時代を超えての城: 1423年、1858年、そして1999年の順に。</ figcaption >
</ figure >
figureは、コンテンツから暗黙的に参照される場合もあります:
< article >
< h1 > 議会での財政交渉が行き詰まり、締め切りが迫る</ h1 >
< figure >
< img src = "obama-reid.jpeg" alt = "オバマとリードがオーバルオフィスで笑顔で座っています。" >
< figcaption > バラク・オバマとハリー・リード。ホワイトハウスの報道写真。</ figcaption >
</ figure >
< p > 火曜日、議会での財政行き詰まりを終わらせるための交渉が失速し、両院は政府を再開し、国の借入権限を引き上げる方法を模索していましたが、木曜日の締め切りが迫っていました。</ p >
...
</ article >
figcaption 要素
全ての現行エンジンでサポートされています。
figure要素の最初または最後の子要素として。
HTMLElementを使用します。
figcaption要素は、親figure要素の残りの内容を説明するキャプションまたは凡例を表します。
この要素には、ソースに関する追加情報を含めることができます:
< figcaption >
< p > アヒル。</ p >
< p >< small > 写真提供: 🌟 ニュース</ small ></ p >
</ figcaption >
< figcaption >
< p > 3部屋のアパートの平均家賃(非営利アパートを除く)</ p >
< p > チューリッヒ統計局 — < time datetime = 2017-11-14 > 2017年11月14日</ time ></ p >
</ figcaption >
main要素すべての現在のエンジンでサポートされています。
main要素である場合に限ります。
HTMLElementを使用します。
main 要素は、文書の主要な内容を表します。
文書には、main
要素が1つ以上あってはなりません。ただし、属性が指定されていない場合に限ります。
階層的に正しい main 要素 とは、祖先要素が html、body、div、formに限られる要素です。また、アクセシブルな名前がない場合、および独立カスタム要素も含まれます。各main要素は、階層的に正しい
main 要素でなければなりません。
この例では、ページの各コンポーネントがボックスでレンダリングされるプレゼンテーションを使用しています。ページのメインコンテンツ(ヘッダー、フッター、ナビゲーションバー、サイドバー以外の部分)をラップするために、main要素が使用されています。
<!DOCTYPE html>
< html lang = "en" >
< title > RPG System 17</ title >
< style >
header , nav , aside , main , footer {
margin : 0.5 em ; border : thin solid ; padding : 0.5 em ;
background : #EFF ; color : black ; box-shadow : 0 0 0.25 em #033 ;
}
h1 , h2 , p { margin : 0 ; }
nav , main { float : left ; }
aside { float : right ; }
footer { clear : both ; }
</ style >
< header >
< h1 > System Eighteen</ h1 >
</ header >
< nav >
< a href = "../16/" > ← System 17</ a >
< a href = "../18/" > RPXIX →</ a >
</ nav >
< aside >
< p > This system has no HP mechanic, so there's no healing.
</ aside >
< main >
< h2 > Character creation</ h2 >
< p > Attributes (magic, strength, agility) are purchased at the cost of one point per level.</ p >
< h2 > Rolls</ h2 >
< p > Each encounter, roll the dice for all your skills. If you roll more than the opponent, you win.</ p >
</ main >
</ footer >
< p > Copyright © 2013
</ footer >
</ html >
次の例では、複数のmain要素が使用され、スクリプトが使用されてナビゲーションがサーバーラウンドトリップなしで機能し、現在のもの以外には属性が設定されます:
<!doctype html>
< html lang = en-CA >
< meta charset = utf-8 >
< title > … </ title >
< link rel = stylesheet href = spa.css >
< script src = spa.js async ></ script >
< nav >
< a href = / > Home</ a >
< a href = /about > About</ a >
< a href = /contact > Contact</ a >
</ nav >
< main >
< h1 > Home</ h1 >
…
</ main >
< main hidden >
< h1 > About</ h1 >
…
</ main >
< main hidden >
< h1 > Contact</ h1 >
…
</ main >
</ footer > Made with ❤️ by < a href = https://example.com/ > Example 👻</ a > .</ footer >
search要素現在のエンジンではサポートされていません。
HTMLElementを使用します。
search要素は、検索やフィルタリング操作に関連するフォームコントロールやその他のコンテンツを含む文書やアプリケーションの一部を表します。これには、ウェブサイトやアプリケーションの検索、現在のウェブページの検索結果の検索やフィルタリング、またはインターネット全体やその一部に対する検索機能が含まれる場合があります。
search要素は、検索結果を提示するためだけに使用するのは適切ではありませんが、「クイック検索」結果の一部として提案やリンクを含めることができます。代わりに、検索結果のウェブページはそのウェブページの主なコンテンツの一部として提示されることが期待されます。
次の例では、著者がウェブページのheader内に検索フォームを含めています:
< header >
< h1 >< a href = "/" > My fancy blog</ a ></ h1 >
...
< search >
< form action = "search.php" >
< label for = "query" > Find an article</ label >
< input id = "query" name = "q" type = "search" >
< button type = "submit" > Go!</ button >
</ form >
</ search >
</ header >
この例では、著者がウェブアプリケーションの検索機能を完全にJavaScriptで実装しています。サーバー側の送信を行うためにform要素は使用されていませんが、含まれているsearch要素が子孫コンテンツの目的を検索機能として意味的に識別しています。
< search >
< label >
Find and filter your query
< input type = "search" id = "query" >
</ label >
< label >
< input type = "checkbox" id = "exact-only" >
Exact matches only
</ label >
< section >
< h3 > Results found:</ h3 >
< ul id = "results" >
< li >
< p >< a href = "services/consulting" > Consulting services</ a ></ p >
< p >
Find out how can we help you improve your business with our integrated consultants, Bob and Bob.
</ p >
</ li >
...
</ ul >
<!--
when a query returns or filters out all results
render the no results message here
-->
< output id = "no-results" ></ output >
</ section >
</ search >
次の例では、ページに2つの検索機能があります。最初の機能はウェブページのheaderにあり、ウェブサイトの内容を検索するためのグローバルメカニズムとして機能します。その目的は指定されたtitle属性によって示されています。2つ目はページの主なコンテンツの一部として含まれており、現在のページの内容を検索およびフィルタリングするためのメカニズムを表しています。目的を示す見出しを含んでいます。
< body >
< header >
...
< search title = "Website" >
...
</ search >
</ header >
< main >
< h1 > Hotels near your location</ h1 >
< search >
< h2 > Filter results</ h2 >
...
</ search >
< article >
<!-- search result content -->
</ article >
</ main >
</ body >
div要素すべての現在のエンジンでサポートされています。
すべての現在のエンジンでサポートされています。
dl要素の子として。
dl要素の子の場合: 1つ以上の
dt要素に続いて1つ以上の
dd要素が含まれ、オプションでスクリプトサポート要素が含まれることがあります。
dl要素の子でない場合: フローコンテンツ。
[Exposed =Window ]
interface HTMLDivElement : HTMLElement {
[HTMLConstructor ] constructor ();
// 廃止されたメンバーも含まれています
};
div要素には特別な意味はありません。要素は子要素を表現します。連続した要素のグループに共通のセマンティクスをマークアップするために、class、lang、およびtitle属性と一緒に使用できます。また、dl要素内で使用し、dtおよびdd要素のグループをラップするために使用できます。
著者には、div要素を最後の手段として使用することを強くお勧めします。div要素の代わりにより適切な要素を使用すると、読者にとってのアクセシビリティが向上し、著者にとってのメンテナンスが容易になります。
たとえば、ブログ記事はarticleでマークアップし、章はsectionでマークアップし、ページのナビゲーション補助はnavでマークアップし、フォームコントロールのグループはfieldsetでマークアップします。
一方、div要素は、スタイル目的で、または同じ方法で注釈を付ける複数の段落をセクション内でラップするために便利です。以下の例では、2つの段落の言語を一度に設定する方法としてdiv要素を使用しており、2つの段落要素に個別に言語を設定する代わりに、div要素内でまとめています:
< article lang = "en-US" >
< h1 > My use of language and my cats</ h1 >
< p > My cat's behavior hasn't changed much since her absence, except
that she plays her new physique to the neighbors regularly, in an
attempt to get pets.</ p >
< div lang = "en-GB" >
< p > My other cat, coloured black and white, is a sweetie. He followed
us to the pool today, walking down the pavement with us. Yesterday
he apparently visited our neighbours. I wonder if he recognises that
their flat is a mirror image of ours.</ p >
< p > Hm, I just noticed that in the last paragraph I used British
English. But I'm supposed to write in American English. So I
shouldn't say "pavement" or "flat" or "colour"...</ p >
</ div >
< p > I should say "sidewalk" and "apartment" and "color"!</ p >
</ article >
a要素すべての現在のエンジンでサポートされています。
すべての現在のエンジンでサポートされています。
href属性を持つ場合: インタラクティブコンテンツ.
a要素の子孫、またはtabindex属性を指定された子孫が含まれていてはいけません。
href — ハイパーリンクのアドレス
target — ナビゲーブルによるハイパーリンク ナビゲーション
download
—
リソースをナビゲートする代わりにダウンロードするかどうか、およびその場合のファイル名
ping — pingするURL
rel — ハイパーリンクを含む場所とリソースの間の関係
hreflang
—
リンク先リソースの言語
type — リンク先リソースの種類を示すヒント
referrerpolicy
— 要素によって開始されるフェッチの参照ポリシー
href属性を持つ場合:
著者向け; 実装者向け.
[Exposed =Window ]
interface HTMLAnchorElement : HTMLElement {
[HTMLConstructor ] constructor ();
[CEReactions ] attribute DOMString target ;
[CEReactions ] attribute DOMString download ;
[CEReactions ] attribute USVString ping ;
[CEReactions ] attribute DOMString rel ;
[SameObject , PutForwards =value ] readonly attribute DOMTokenList relList ;
[CEReactions ] attribute DOMString hreflang ;
[CEReactions ] attribute DOMString type ;
[CEReactions ] attribute DOMString text ;
[CEReactions ] attribute DOMString referrerPolicy ;
// also has obsolete members
};
HTMLAnchorElement includes HTMLHyperlinkElementUtils ;
要素がa要素であり、href属性を持つ場合、
その要素はハイパーリンク(ハイパーテキストアンカー)をその内容でラベル付けします。
要素がa要素であり、href属性を持たない場合、
その要素はプレースホルダーとして機能し、関連性がある場合にリンクが置かれる可能性がある場所を表します。これは、要素の内容のみで構成されます。
target、
download、
ping、
rel、hreflang、
type、
およびreferrerpolicy
属性は、href属性が存在しない場合、省略する必要があります。
要素にitemprop属性が指定されている場合、そのa要素にはhref属性も指定されている必要があります。
サイトが全ページで一貫したナビゲーションツールバーを使用している場合、そのページ自体にリンクする通常のリンクはa要素でマークアップできます:
< nav >
< ul >
< li > < a href = "/" > ホーム</ a > </ li >
< li > < a href = "/news" > ニュース</ a > </ li >
< li > < a > 例</ a > </ li >
< li > < a href = "/legal" > 法的情報</ a > </ li >
</ ul >
</ nav >
href、target、download、
ping、
およびreferrerpolicy
属性は、ユーザーがハイパーリンクを辿るまたはハイパーリンクをダウンロードする際の動作に影響します。rel、
hreflang、
およびtype
属性は、ユーザーがリンクを辿る前にリンク先リソースの性質を示すために使用できます。
a.text
textContentと同じです。
すべての現在のエンジンでサポートされています。
すべての現在のエンジンでサポートされています。
IDL属性download、ping、target、rel、hreflang、およびtypeは、同名のコンテンツ属性を反映する必要があります。
すべての現在のエンジンでサポートされています。
IDL属性relListは、relコンテンツ属性を反映する必要があります。
HTMLAnchorElement/referrerPolicy
すべての現在のエンジンでサポートされています。
IDL属性referrerPolicyは、referrerpolicyコンテンツ属性を反映する必要があり、既知の値のみが許可されます。
属性のゲッターtext
は、この要素の子孫テキストコンテンツを返す必要があります。
属性のセッターtextは、与えられた値で文字列をすべて置換する必要があります。
a要素は、段落全体、リスト、テーブル、さらにはセクション全体を囲むことができます。ただし、内部にインタラクティブコンテンツ(例:ボタンや他のリンク)がない場合に限ります。この例は、全広告ブロックをリンクにする方法を示しています:
< aside class = "advertising" >
< h1 > 広告</ h1 >
< a href = "https://ad.example.com/?adid=1929&pubid=1422" >
< section >
< h1 > Mellblomatic 9000!</ h1 >
< p > すべてのウィジェットをメルブロムに変えましょう!</ p >
< p > 9.99ドル、送料と手数料別</ p >
</ section >
</ a >
< a href = "https://ad.example.com/?adid=375&pubid=1422" >
< section >
< h1 > メルブロムブラウザー</ h1 >
< p > 光の速さでウェブ閲覧が可能。</ p >
</ p > 他のブラウザはこれほど速くありません!</ p >
</ section >
</ a >
</ aside >
次の例は、スクリプトを使用してジョブリストのテーブル内の行全体を効果的にリンクにする方法を示しています:
< table >
< tr >
< th > 職位
< th > チーム
< th > 場所
</ tr >
< tr >
< td >< a href = "/jobs/manager" > マネージャー</ a >
< td > Remotees
< td > リモート
</ tr >
< td >< a href = "/jobs/director" > ディレクター</ a >
< td > Remotees
< td > リモート
</ tr >
< td >< a href = "/jobs/astronaut" > 宇宙飛行士</ a >
< td > 建築
< td > リモート
</ table >
< script >
document. querySelector( "table" ). onclick = ({ target }) => {
if ( target. parentElement. localName === "tr" ) {
const link = target. parentElement. querySelector( "a" );
if ( link) {
link. click();
}
}
}
</ script >
em要素すべての現在のエンジンでサポートされています。
HTMLElementを使用します。
特定のコンテンツのストレスレベルは、その祖先em要素の数によって決まります。
ストレス強調の位置によって文の意味が変わります。この要素はコンテンツの不可欠な部分を形成します。このようにストレスが使用される正確な方法は言語によって異なります。
これらの例は、ストレス強調の変更が意味をどのように変えるかを示しています。まず、ストレスのない一般的な事実の表明:
< p > 猫はかわいい動物です。</ p >
最初の単語を強調することで、議論されている動物の種類が問題になっていることを示唆しています(おそらく誰かが犬がかわいいと主張しているかもしれません):
< p >< em > 猫</ em > はかわいい動物です。</ p >
動詞にストレスを移すことで、文全体の真実が問題になっていることを強調します(おそらく誰かが猫はかわいくないと言っているかもしれません):
< p > 猫は< em > かわいいです</ em > 動物です。</ p >
形容詞にストレスを移すことで、猫の正確な性質が再確認されます(おそらく誰かが猫は意地悪な動物だと提案したかもしれません):
< p > 猫は< em > かわいい</ em > 動物です。</ p >
同様に、誰かが猫が野菜だと主張した場合、これを訂正するために最後の単語を強調するかもしれません:
< p > 猫はかわいい< em > 動物</ em > です。</ p >
文全体を強調することで、話者がこのポイントを強く伝えようとしていることが明らかになります。この種のストレス強調は通常、句読点にも影響を与えるため、ここでは感嘆符が使用されています。
< p >< em > 猫はかわいい動物です!</ em ></ p >
怒りとかわいさの強調を混ぜると、次のようなマークアップが使用されることがあります:
< p >< em > 猫は</ em > かわいい</ em > 動物です!</ p >
strong
要素すべての現在のエンジンでサポートされています。
HTMLElementを使用します。
strong要素は、その内容に強い重要性、真剣さ、または緊急性を示します。
重要性: strong要素は、見出し、キャプション、または段落内で、他の部分よりも重要な部分を区別するために使用できます(これは、サブヘッディングをマークアップするために適したhgroup要素とは異なります)。
たとえば、前の段落の最初の単語は、strongでマークアップされ、段落の他の詳細なテキストと区別されています。
真剣さ: strong要素は、警告や注意の通知をマークアップするために使用できます。
緊急性: strong要素は、ドキュメントの他の部分よりもユーザーが早く見る必要がある内容を示すために使用できます。
コンテンツの相対的な重要度は、その祖先strong要素の数によって決まります。各strong要素は、その内容の重要性を高めます。
strong要素でテキストの重要性を変更しても、文の意味は変わりません。
ここでは、「chapter」という言葉と実際の章番号は単なる決まり文句であり、実際の章の名前はstrongでマークアップされています:
< h1 > Chapter 1: < strong > The Praxis</ strong ></ h1 >
次の例では、キャプション内の図の名前がstrongでマークアップされており、決まり文句のテキスト(前)と説明(後)と区別されています:
< figcaption > Figure 1. < strong > Ant colony dynamics</ strong > . The ants in this colony are
affected by the heat source (upper left) and the food source (lower right).</ figcaption >
次の例では、見出しは実際には「Flowers, Bees, and Honey」ですが、著者は見出しに軽いユーモアを追加しています。strong要素は、最初の部分をマークアップして後の部分と区別するために使用されています。
< h1 >< strong > Flowers, Bees, and Honey</ strong > and other things I don't understand</ h1 >
以下は、ゲーム内の警告通知の例であり、各部分がその重要度に応じてマークアップされています:
< p >< strong > Warning.</ strong > This dungeon is dangerous.
< strong > Avoid the ducks.</ strong > Take any gold you find.
< strong >< strong > Do not take any of the diamonds</ strong > ,
they are explosive and < strong > will destroy anything within
ten meters.</ strong ></ strong > You have been warned.</ p >
次の例では、strong要素が、ユーザーが最初に読むべき部分を示すために使用されています。
< p > Welcome to Remy, the reminder system.</ p >
< p > Your tasks for today:</ p >
< ul >
< li >< p >< strong > Turn off the oven.</ strong ></ p ></ li >
< li >< p > Put out the trash.</ p ></ li >
< li >< p > Do the laundry.</ p ></ li >
</ ul >
small
要素すべての現在のエンジンでサポートされています。
HTMLElementを使用します。
small要素は、サイドコメントや小さな文字で表されるテキストを表します。
小さな文字には、免責事項、注意書き、法的制約、または著作権が含まれることが多いです。また、出典の表示やライセンス要件の満たしに使用されることもあります。
small要素は、em要素で強調されたテキストやstrong要素で重要とマークされたテキストの重要性を「低減」するものではありません。強調されていないテキストや重要でないテキストをマークするには、それぞれemまたはstrong要素でマークアップしないでください。
small要素は、複数の段落、リスト、またはテキストセクションなど、長いテキストスパンに使用すべきではありません。短いテキストランにのみ使用されることを意図しています。たとえば、利用規約をリストするページのテキストは、small要素の適切な候補ではありません。このような場合、そのテキストはサイドコメントではなく、ページの主要なコンテンツです。
small要素は、小見出しに使用してはなりません。その目的には、hgroup要素を使用してください。
この例では、small要素は、ホテルの部屋の価格に付加価値税が含まれていないことを示すために使用されています:
< dl >
< dt > Single room
< dd > 199 € < small > breakfast included, VAT not included</ small >
< dt > Double room
< dd > 239 € < small > breakfast included, VAT not included</ small >
</ dl >
この2番目の例では、small要素が記事のサイドコメントに使用されています。
< p > Example Corp today announced record profits for the
second quarter < small > (Full Disclosure: Foo News is a subsidiary of
Example Corp)</ small > , leading to speculation about a third quarter
merger with Demo Group.</ p >
これは、メインテキストの流れから外れた複数の段落にわたるサイドバーとは異なります。次の例では、同じ記事からのサイドバーが示されています。このサイドバーには、サイドバー内の情報の出典を示す小さな文字が含まれています。
< aside >
< h1 > Example Corp</ h1 >
< p > This company mostly creates small software and Web
sites.</ p >
< p > The Example Corp company mission is "To provide entertainment
and news on a sample basis".</ p >
< p >< small > Information obtained from < a
href = "https://example.com/about.html" > example.com</ a > home
page.</ small ></ p >
</ aside >
この最後の例では、small要素が重要な小さな文字としてマークされています。
< p >< strong >< small > Continued use of this service will result in a kiss.</ small ></ strong ></ p >
s
要素すべての現在のエンジンでサポートされています。
HTMLElementを使用します。
s要素は、もはや正確でない、または関連性がない内容を表します。
s要素は文書の編集を示す際には適切ではありません。文書から削除されたテキストをマークするには、del要素を使用してください。
この例では、製品の推奨小売価格がもはや関連性がないとマークされており、その製品に新しいセール価格が適用されています。
< p > Buy our Iced Tea and Lemonade!</ p >
< p >< s > Recommended retail price: $3.99 per bottle</ s ></ p >
< p >< strong > Now selling for just $2.99 a bottle!</ strong ></ p >
cite要素すべての現在のエンジンでサポートされています。
HTMLElementを使用します。
cite要素は、作品のタイトル (例:
書籍、論文、エッセイ、詩、スコア、曲、脚本、映画、テレビ番組、ゲーム、彫刻、絵画、劇場公演、演劇、オペラ、ミュージカル、展覧会、法律事件報告、コンピュータプログラムなど)
を表します。これは引用されている作品または詳細に参照されている作品 (つまり、引用) である可能性があり、またはただ言及されているだけの作品である場合もあります。
人名は作品のタイトルではありません—たとえ人々がその人を作品と呼んだとしても—したがって、この要素を使用して人名をマークアップしてはなりません。(場合によっては、b要素が名前に適しているかもしれません。例えば、有名人の名前が強調されるゴシップ記事などでは、名前がキーワードとして異なるスタイルで表示されます。その他の場合、要素が本当に必要である場合は、span要素を使用できます。)
次の例は、cite要素の典型的な使用例を示しています:
<p>私のお気に入りの本は<cite>The Reality Dysfunction</cite>です。著者はPeter F. Hamiltonです。私のお気に入りの漫画は<cite>Pearls Before Swine</cite>です。作者はStephan Pastisです。私のお気に入りの曲は<cite>Jive Samba</cite>です。演奏者はCannonball Adderley Sextetです。</p>
これは正しい使用例です:
<p>Wikipediaの記事<cite>HTML</cite>によると、2008年2月中旬の時点で、属性値を引用符なしで残すことは危険です。これは明らかに過度に簡略化されています。</p>
しかし、次の例は正しくありません。cite要素には、作品のタイトル以上のものが含まれています:
<!-- この例をコピーしないでください、これは悪い使用例です! -->
<p>WikipediaのHTMLに関する記事<cite>によると、2008年2月中旬の時点で、属性値を引用符なしで残すことは危険です。これは明らかに過度に簡略化されています。</p>
cite要素は、参考文献の書誌において重要な役割を果たしますが、これはタイトルのみをマークするために使用されます:
<p><cite>世界人権宣言</cite>、国連、1948年12月。総会決議217 A (III) によって採択されました。</p>
引用は引用文ではありません (これはq要素に適しています)。
これは誤った使用例です。citeは引用文には適していません:
<p><cite>これは間違いです!</cite>とイアンは言いました。</p>
これは誤った使用例でもあります。なぜなら、人間は作品ではないからです:
<p><q>これはまだ間違いです!</q>と<cite>イアン</cite>が言いました。</p>
正しい使用例では、cite要素を使用しません:
<p><q>これは正しいです</q>とイアンは言いました。</p>
前述のように、b要素は、特定の種類のドキュメントで名前をキーワードとしてマークするために使用することができます:
<p>そして<b>イアン</b>は言いました<q>ゴシップ記事では、これは正しいかもしれません!</q>。</p>
q要素すべての現在のエンジンでサポートされています。
cite — 引用の元や編集に関する詳細へのリンク
HTMLQuoteElementを使用します。
q要素は、他のソースから引用されたフレージングコンテンツを表します。
要素の内容を引用する引用符などの句読点は、q要素の直前、直後、または内部に表示されてはなりません。それらはユーザーエージェントによってレンダリングに挿入されます。
q要素内のコンテンツは、別のソースから引用されたものでなければなりません。そのアドレスがある場合は、cite属性に引用することができます。ソースは、例えば小説や脚本の登場人物を引用する場合のように、架空のものであっても構いません。
cite属性が存在する場合、それはスペースに囲まれた有効なURLでなければなりません。対応する引用リンクを取得するためには、属性の値をURLを解析し、要素のノードドキュメントに対して相対的に処理する必要があります。ユーザーエージェントはユーザーがそのような引用リンクに従うことを許可するかもしれませんが、それらは主にプライベート用途
(例: 引用の使用状況に関する統計を収集するサーバーサイドスクリプトなど) を目的としており、読者向けではありません。
q要素は、引用を表さない引用符の代わりに使用してはなりません。例えば、q要素を皮肉な発言のマークアップに使用することは不適切です。
q要素を使用して引用をマークアップすることは完全に任意です。q要素を使用せずに明示的な引用符を使用することも同様に正しいです。
以下は、q要素の使用例です:
<p>The man said <q>Things that are impossible just take longer</q>. I disagreed with him.</p>
次の例では、q要素に明示的な引用リンクがあり、また引用が外部にあります:
<p>The W3C page <cite>About W3C</cite> says the W3C's mission is <q cite="https://www.w3.org/Consortium/">To lead the World Wide Web to its full potential by developing protocols and guidelines that ensure long-term growth for the Web</q>. I disagree with this mission.</p>
次の例では、引用自体に引用が含まれています:
<p>In <cite>Example One</cite>, he writes <q>The man said <q>Things that are impossible just take longer</q>. I disagreed with him</q>. Well, I disagree even more!</p>
次の例では、q要素の代わりに引用符が使用されています:
<p>His best argument was ❝I disagree❞, which I thought was laughable.</p>
次の例では、引用はなく、引用符は単語を示すために使用されています。この場合、q要素を使用するのは不適切です。
<p>The word "ineffable" could have been used to describe the disaster resulting from the campaign's mismanagement.</p>
dfn
要素すべての現在のエンジンでサポートされています。
dfn 要素の
子孫があってはなりません。
title 属性はこの
要素に特別な意味があります: 完全な用語または略語の展開
HTMLElementを使用します。
dfn 要素は表す定義された用語のインスタンスです。段落、定義リストグループ、またはセクションが最も近い祖先であるdfn
要素も、その用語の定義を含まなければなりません。
定義用語: dfn 要素がtitle 属性を持っている場合、
その属性の正確な値が定義されている用語です。そうでない場合、もし正確に1つの要素子ノードと
Text
ノードを含み、その子要素がabbr 要素で
title 属性を持っている場合、
その属性の正確な値が定義されている用語です。それ以外の場合は、子孫テキストコンテンツが
dfn 要素の
定義されている用語を示します。
title 属性が
dfn 要素に存在する場合、
それは定義されている用語のみを含まなければなりません。
title 属性は
祖先要素には影響しません。
a 要素がdfn 要素にリンクしている場合、
それはdfn
要素によって定義された用語のインスタンスを表します。
次の断片では、「Garage Door Opener」という用語が最初の段落で定義され、その後に2番目の段落で使用されます。どちらの場合も、実際に表示されるのは略語です。
< p > The < dfn >< abbr title = "Garage Door Opener" > GDO</ abbr ></ dfn >
is a device that allows off-world teams to open the iris.</ p >
<!-- ... later in the document: -->
< p > Teal'c activated his < abbr title = "Garage Door Opener" > GDO</ abbr >
and so Hammond ordered the iris to be opened.</ p >
a 要素を追加することで、
参照
を明示的にすることができます:
< p > The < dfn id = gdo >< abbr title = "Garage Door Opener" > GDO</ abbr ></ dfn >
is a device that allows off-world teams to open the iris.</ p >
<!-- ... later in the document: -->
< p > Teal'c activated his < a href = #gdo > < abbr title = "Garage Door Opener" > GDO</ abbr > </ a >
and so Hammond ordered the iris to be opened.</ p >
abbr
要素すべての現在のエンジンでサポートされています。
title属性がこの要素に特別な意味を持ちます:
省略形の完全な用語または展開形
HTMLElementを使用します。
abbr要素は、略語または頭字語を表します。省略形の展開をオプションで含むことができます。title属性を使用して、省略形の展開を提供できます。指定されている場合、属性には省略形の展開のみが含まれている必要があります。
以下の段落には、abbr要素でマークアップされた略語が含まれています。この段落は、「Web
Hypertext Application Technology Working Group」という用語を定義しています。
< p > The < dfn id = whatwg >< abbr
title = "Web Hypertext Application Technology Working Group" > WHATWG</ abbr ></ dfn >
is a loose unofficial collaboration of web browser manufacturers and
interested parties who wish to develop new technologies designed to
allow authors to write and deploy Applications over the World Wide
Web.</ p >
別の書き方では、次のようになります。
< p > The < dfn id = whatwg > Web Hypertext Application Technology
Working Group</ dfn > (< abbr
title = "Web Hypertext Application Technology Working Group" > WHATWG</ abbr > )
is a loose unofficial collaboration of web browser manufacturers and
interested parties who wish to develop new technologies designed to
allow authors to write and deploy Applications over the World Wide
Web.</ p >
この段落には2つの略語があります。1つだけが定義されていることに注目してください。展開が関連付けられていないもう1つの略語には、abbr要素が使用されていません。
< p > The
< abbr title = "Web Hypertext Application Technology Working Group" > WHATWG</ abbr >
started working on HTML5 in 2004.</ p >
この段落は、略語をその定義にリンクしています。
< p > The < a href = "#whatwg" >< abbr
title = "Web Hypertext Application Technology Working Group" > WHATWG</ abbr ></ a >
community does not have much representation from Asia.</ p >
この段落は、展開を提供せずに略語をマークアップしています。これは、略語にスタイルを適用するためのフック(例:スモールキャップス)として使用される可能性があります。
< p > Philip` and Dashiva both denied that they were going to
get the issue counts from past revisions of the specification to
backfill the < abbr > WHATWG</ abbr > issue graph.</ p >
略語が複数形である場合、展開の文法的な数(単数形対複数形)は、要素の内容の文法的な数と一致している必要があります。
ここでは複数形が要素の外にあるため、展開は単数形です。
< p > Two < abbr title = "Working Group" > WG</ abbr > s worked on
this specification: the < abbr > WHATWG</ abbr > and the
< abbr > HTMLWG</ abbr > .</ p >
ここでは複数形が要素の中にあるため、展開は複数形です。
< p > Two < abbr title = "Working Groups" > WGs</ abbr > worked on
this specification: the < abbr > WHATWG</ abbr > and the
< abbr > HTMLWG</ abbr > .</ p >
略語は必ずしもこの要素でマークアップする必要はありません。この要素が役立つと考えられるのは次の場合です。
abbr要素をtitle属性と共に使用することは、展開をインラインで含める(例:括弧内)ための代替手段となります。
abbr要素とtitle属性でマークアップするか、インラインで展開を含めることを奨励されています。
abbr要素をtitle属性なしで使用できます。
一度title属性で展開を提供しても、同じ文書内でtitle属性がないが同じ内容を持つ他のabbr要素が、同じ展開を持つように動作するとは限りません。すべてのabbr要素は独立しています。
ruby
要素すべての現在のエンジンでサポートされています。
HTMLElementを使用します。
ruby要素は、フレージングコンテンツの1つ以上のスパンにルビ注釈を付けることができます。ルビ注釈は、主に東アジアのタイポグラフィで発音のガイドとして使用されるベーステキストに沿って表示される短いテキストです。日本語では、この形式のタイポグラフィは「ふりがな」とも呼ばれます。
ruby要素のコンテンツモデルは、次の1つ以上のシーケンスで構成されます。
次のいずれか1つ:
フレージングコンテンツ、ただし、ruby要素およびその子孫要素は含まれません。
次のいずれか1つ:
rubyおよびrt要素は、特に以下に説明するような、さまざまな種類の注釈に使用できます。日本語ルビやそのレンダリング方法の詳細については、日本語組版処理の要件を参照してください。[JLREQ]
執筆時点では、CSSはまだHTMLのruby要素のレンダリングを完全に制御する方法を提供していません。今後、CSSが以下に説明するスタイルをサポートするように拡張されることが期待されています。
1つ以上のひらがなまたはカタカナ文字(ルビ注釈)が、各表意文字(ベーステキスト)に配置されます。これは、漢字の読みを提供するために使用されます。
< ruby > B< rt > annotation</ ruby >
この例では、各注釈が単一のベース文字に対応していることに注目してください。
< ruby > 君< rt > くん</ ruby >< ruby > 子< rt > し</ ruby > は< ruby > 和< rt > わ</ ruby > して< ruby > 同< rt > どう</ ruby > ぜず。
君子は和して同ぜず。
この例は、2つのベーステキストと2つの注釈(それぞれに1つ)を持つ1つのruby要素を使用して、次のように書くこともできます。これは、2つのベーステキストと1つの注釈(上記のマークアップのように)を持つruby要素2つと同じです。
< ruby > 君< rt > くん</ rt > 子< rt > し</ ruby > は< ruby > 和< rt > わ</ ruby > して< ruby > 同< rt > どう</ ruby > ぜず。
これは前のケースと似ていますが、複合語(ベーステキスト)にある各表意文字に、その読みがひらがなまたはカタカナ文字(ルビ注釈)で提供されます。違いは、ベーステキストのセグメントが互いに独立しているのではなく、複合語を形成していることです。
< ruby > B< rt > annotation</ rt > B</ ruby >
この例では、各注釈が再び単一のベース文字に対応していることに注意してください。この例では、各複合語(熟語)は単一のruby要素に対応しています。
ここでのレンダリングは、各注釈が対応するベース文字の上(または縦書きでは横)に配置され、隣接する文字に重ならないことが期待されます。
< ruby > 鬼< rt > き</ rt > 門< rt > もん</ rt ></ ruby > の< ruby > 方< rt > ほう</ rt > 角< rt > がく</ rt ></ ruby > を< ruby > 凝< rt > ぎょう</ rt > 視</ rt > し</ rt ></ ruby > する
鬼門の方角を凝視 する
これは前のケースと意味的には同じです(ベース複合語の各個別表意文字には、ひらがなまたはカタカナ文字の注釈が付けられます)が、レンダリングはより複雑な熟語ルビレンダリングです。
これは、複合語に対する単一ルビの同じ例です。異なるレンダリングは、異なるスタイリング(例:CSS)を使用して達成されることが期待されており、ここでは示されていません。
< ruby > 鬼< rt > き</ rt > 門< rt > もん</ rt ></ ruby > の< ruby > 方< rt > ほう</ rt > 角< rt > がく</ rt ></ ruby > を< ruby > 凝< rt > ぎょう</ rt > 視</ rt > し</ rt ></ ruby > する
注釈は、発音ではなくベーステキストの意味を説明します。そのため、ベーステキストと注釈の両方が複数の文字にまたがることがあります。
< ruby > BASE< rt > annotation</ ruby >
ここでは、複合語に対して対応するカタカナが注釈として与えられています。
< ruby > 境界面< rt > インターフェース</ ruby >
境界面
ここでは、複合語に対して英語の翻訳が注釈として提供されています。
< ruby lang = "ja" > 編集者< rt lang = "en" > editor</ ruby >
編集者
発音が複数のベース文字に対応する場合、1対1のマッピングが難しい場合があります(英語では、「Colonel」や「Lieutenant」などの単語が、一部の方言では個々の文字に発音を直接対応させることが不明瞭な例です)。
この例では、花の種の名前に対して発音がグループルビを使用して提供されています:
< ruby > 紫陽花< rt > あじさい</ ruby >
紫陽花
時々、上記で説明したルビスタイルが組み合わさることがあります。
これが結果的に、同じ単一のベースセグメントをカバーする2つの注釈になる場合、注釈はただ背中合わせに配置することができます。
< ruby > BASE< rt > annotation 1< rt > annotation 2</ ruby >
< ruby > B< rt > a< rt > a</ ruby >< ruby > A< rt > a< rt > a</ ruby >< ruby > S< rt > a< rt > a</ ruby >< ruby > E< rt > a< rt > a</ ruby >
この作為的な例では、いくつかのシンボルに英語とフランス語で名前が付けられています。
< ruby >
♥ < rt > Heart < rt lang = fr > Cœur </ rt >
☘ < rt > Shamrock < rt lang = fr > Trèfle </ rt >
✶ < rt > Star </ rt lang = fr > Étoile </ rt >
</ ruby >
次のようなより複雑な状況では、ネストされたruby要素を使用して内部注釈を付け、次にそのruby全体に「外側」レベルで注釈を付けます。
< ruby >< ruby > B< rt > a</ rt > A</ rt > n</ rt > S</ rt > t</ rt > E</ rt > n</ rt ></ ruby >< rt > annotation</ ruby >
ここでは、発音と意味の両方がルビ注釈で示されています。ネストされたruby要素の注釈は、各ベース文字に対して単一ルビの発音注釈を提供し、外側のrt要素の子であるruby要素の注釈は、ひらがなを使用して意味を提供します。
< ruby >< ruby > 東< rt > とう</ rt > 南</ rt > なん</ rt ></ ruby >< rt > たつみ</ rt ></ ruby > の方角
東南 の方角
これは同じ例ですが、意味が日本語ではなく英語で与えられています。
< ruby >< ruby > 東< rt > とう</ rt > 南< rt > なん</ rt ></ ruby >< rt lang = en > Southeast</ rt ></ ruby > の方角
東南 の方角
ルビ 要素内で、
ルビ 要素の
祖先を持たない場合、コンテンツはセグメント化され、セグメントは3つのカテゴリに分類されます: 基本文セグメント、注釈
セグメント、無視セグメント。無視セグメントはドキュメントのセマンティクスの一部ではありません(これらは一部の
要素間の空白やrp 要素で構成されており、
後者はルビを全くサポートしないレガシーユーザーエージェントのために使用されます)。基本文セグメントは重複することが
あり(DOMの任意の位置で2つのセグメントが重複する制限があり、重複するセグメントの開始点が重複するセグメント
より早い場合、同じかそれ以降の終了点を持つ必要があり、終了点が重複するセグメントより遅い場合、同じかそれ以前の開始点
を持つ必要があります)。注釈セグメントはrt 要素に対応しています。各注釈セグメントはbase text segmentと関連付けることができ、
各base text segmentには注釈セグメントが関連付けられることがあります。(準拠したドキュメントでは、各base text segmentには少なくとも
1つの注釈セグメントが関連付けられ、各注釈セグメントは1つのbase text segmentと関連付けられます)。ルビ 要素は、それに含まれる
base text segmentの集合と、それらのbase text segmentと注釈セグメントのマッピングの
結果を表します。セグメントはDOMレンジの観点で説明され、注釈セグメントの範囲は常に
正確に1つの要素で構成されます。[DOM]
特定の時点で、ルビ
要素の内容のセグメンテーションとカテゴリ化は、次のアルゴリズムを実行することで得られる結果です:
base text segments を、各セグメントに潜在的にbase text subsegmentsのリストを含む空のリストとして定義します。
annotation segments を、各セグメントに潜在的にbase text segmentまたはsubsegmentが関連付けられる空のリストとして定義します。
root を、そのアルゴリズムが実行されるruby 要素として定義します。
もしrootにルビ
要素の祖先がある場合、
endとラベル付けされたステップに進みます。
current parent をrootと定義します。
index を0と定義します。
start index をnullと定義します。
parent start index をnullと定義します。
current base text をnullと定義します。
Start mode: もしindexがcurrent parentの子ノードの数以上である場合、end modeとラベル付けされたステップに進みます。
もしindex番目のcurrent parentのノードがrt 要素またはrp 要素である場合、annotation
modeとラベル付けされたステップに進みます。
start index にindexの値を設定します。
Base mode: もしindex番目のcurrent parentのノードがruby 要素であり、
かつcurrent parentがrootと同じ要素である場合、ルビレベルをプッシュする としてstart modeとラベル付けされたステップに進みます。
もしindex番目のcurrent parentのノードがrt 要素またはrp 要素である場合、現在の基本文を設定する
としてannotation modeとラベル付けされたステップに進みます。
index を1増やします。
Base mode post-increment: もしindexがcurrent parentの子ノードの数以上である場合、end modeとラベル付けされたステップに進みます。
base modeとラベル付けされたステップに戻ります。
Annotation mode: もしindex番目のcurrent parentのノードがrt 要素である場合、ルビ注釈をプッシュする
としてannotation mode incrementとラベル付けされたステップに進みます。
もしindex番目のcurrent parentのノードがrp 要素である場合、annotation
mode incrementとラベル付けされたステップに進みます。
もしindex番目のcurrent parentのノードがText
ノードでないか、もしくはText
ノードであっても要素間の空白でない場合、base modeとラベル付けされたステップに進みます。
Annotation mode increment: lookahead index をindexプラス1と定義します。
Annotation mode white-space skipper: もしlookahead indexがcurrent parentの子ノードの数と等しい場合、end modeとラベル付けされたステップに進みます。
もしlookahead index番目のcurrent parentのノードがrt 要素またはrp 要素である場合、
indexをlookahead indexに設定し、annotation modeとラベル付けされたステップに進みます。
もしlookahead index番目のcurrent parentのノードがText
ノードでないか、もしくはText
ノードであっても要素間の空白でない場合、indexを増やさずにbase
modeとラベル付けされたステップに進み、これまでに見た要素間の空白が次のbase text segmentの一部になります。
lookahead indexを1増やします。
Annotation mode white-space skipperとラベル付けされたステップに進みます。
End mode: もしcurrent parentがrootと同じ要素でない場合、ルビレベルをポップする としてbase mode post-incrementとラベル付けされたステップに進みます。
End: base text segmentsとannotation segmentsを返します。ルビ
要素のコンテンツのうち、それらのリストに記述されていない部分は、暗黙的にignored segmentとなります。
上記のステップで現在の基本文を設定すると記載されている場合、アルゴリズムのその時点で次のステップを実行します:
text rangeを、開始が current parent、start indexであり、終了が current parent、indexであるDOMレンジとして定義します。
new text segmentを、annotation rangeで記述されたbase text segmentとして定義します。
new text segmentをbase text segmentsに追加します。
current base textをnew text segmentとして定義します。
start indexをnullと定義します。
上記のステップでルビレベルをプッシュすると記載されている場合、アルゴリズムのその時点で次のステップを実行します:
current parentをcurrent parentのindex番目のノードとして定義します。
indexを0と定義します。
saved start indexをstart indexの値として設定します。
start indexをnullと定義します。
上記のステップでルビレベルをポップすると記載されている場合、アルゴリズムのその時点で次のステップを実行します:
indexをroot内のcurrent parentの位置として定義します。
current parentをrootとして定義します。
indexを1増やします。
start indexをsaved start indexの値として設定します。
saved start indexをnullと定義します。
上記のステップでルビ注釈をプッシュすると記載されている場合、アルゴリズムのその時点で次のステップを実行します:
rtを、current parentのindex番目のノードであるrt要素として定義します。
annotation rangeを、開始が current parent、indexであり、終了が current parent、indexプラス1であるDOMレンジとして定義します(つまりrtのみを含む)。
new annotation segmentを、annotation rangeで記述された注釈セグメントとして定義します。
もしcurrent base textがnullでない場合、new annotation segmentをcurrent base textに関連付けます。
new annotation segmentをannotation segmentsに追加します。
この例では、日本語のテキスト漢字の各表意文字に、その読みがひらがなで注釈されています。
...
< ruby > 漢< rt > かん</ rt > 字< rt > じ</ rt ></ ruby >
...
これがレンダリングされると次のようになります:

この例では、繁体字中国語のテキスト漢字の各表意文字に、その注音符号が注釈されています。
< ruby > 漢< rt > ㄏㄢˋ</ rt > 字< rt > ㄗˋ</ rt ></ ruby >
これがレンダリングされると次のようになります:

この例では、簡体字中国語のテキスト汉字の各表意文字に、その拼音が注釈されています。
...< ruby > 汉< rt > hàn</ rt > 字< rt > zì</ rt ></ ruby > ...
これがレンダリングされると次のようになります:

このより複雑な例では、「HTML」という頭字語には4つの注釈があります: 頭字語全体に対するもの、HTの文字を「Hypertext」として展開するもの、Mの文字を「Markup」として展開するもの、Lの文字を「Language」として展開するもの。
< ruby >
< ruby > HT< rt > Hypertext</ rt > M< rt > Markup</ rt > L< rt > Language</ rt ></ ruby >
< rt > An abstract language for describing documents and applications
</ ruby >
rt 要素すべての現在のエンジンでサポートされています。
ruby 要素の子要素として。
rt 要素の 終了タグ は、
rt 要素が直後にrt 要素または
rp
要素が続く場合や、親要素内に他のコンテンツがない場合には省略できます。
HTMLElement を使用します。
rt 要素は、ルビ注釈のルビテキストコンポーネントを示します。ruby 要素の子要素として存在する場合、
何も表しませんが、ruby 要素がそのそれが
表すものを決定する一部として使用します。
rt 要素がruby 要素の子要素でない場合、
その子要素と同じものを表します。
rp 要素すべての現在のエンジンでサポートされています。
ruby 要素の子要素として、rt 要素の直前または直後に使用できます。
rp 要素の 終了タグ は、rp 要素が直後にrt 要素または
rp
要素が続く場合や、親要素内に他のコンテンツがない場合には省略できます。
HTMLElement を使用します。
rp
要素は、ルビ注釈のルビテキストコンポーネントの周りに括弧やその他のコンテンツを提供するために使用され、ルビ注釈をサポートしないユーザーエージェントで表示されます。
rp 要素がruby 要素の子要素である場合、
何も表しません。rp 要素がruby 要素の子要素でない場合は、その子要素を表します。
上記の例では、テキスト 漢字 の各表意文字にその発音が注釈されていますが、rp
を使用してレガシーユーザーエージェントで注釈が括弧で表示されるように拡張することができます:
...
< ruby > 漢< rp > (</ rp >< rt > かん</ rt >< rp > )</ rp > 字< rp > (</ rp >< rt > じ</ rt >< rp > )</ rp ></ ruby >
...
準拠するユーザーエージェントではレンダリングは上記のようになりますが、ルビをサポートしないユーザーエージェントでは次のようにレンダリングされます:
... 漢(かん)字(じ)...
セグメントに複数の注釈がある場合、rp
要素は注釈の間にも配置できます。以下は以前の作り込まれた例のコピーで、英語とフランス語で名前が付けられたシンボルがいくつか表示されていますが、今回はrp 要素も含まれています:
< ruby >
♥< rp > : </ rp >< rt > Heart</ rt >< rp > , </ rp >< rt lang = fr > Cœur</ rt >< rp > .</ rp >
☘< rp > : </ rp >< rt > Shamrock</ rt >< rp > , </ rp >< rt lang = fr > Trèfle</ rt >< rp > .</ rp >
✶< rp > : </ rp >< rt > Star</ rt >< rp > , </ rp >< rt lang = fr > Étoile</ rt >< rp > .</ rp >
</ ruby >
これにより、ルビ対応でないユーザーエージェントでのレンダリングは次のようになります:
♥: Heart, Cœur. ☘: Shamrock, Trèfle. ✶: Star, Étoile.
data 要素すべての現在のエンジンでサポートされています。
すべての現在のエンジンでサポートされています。
value — 機械可読の値
[Exposed =Window ]
interface HTMLDataElement : HTMLElement {
[HTMLConstructor ] constructor ();
[CEReactions ] attribute DOMString value ;
};
data 要素は、その内容と、その内容の機械可読形式をvalue属性に関連付けて表します。
value属性は必須です。その値は、要素の内容を機械可読形式で表現したものでなければなりません。
値が日付や時間に関連している場合は、より具体的なtime要素を使用することができます。
この要素はいくつかの目的に使用できます。
この仕様で定義されているマイクロフォーマットやマイクロデータ属性と組み合わせると、この要素はデータ処理者のための機械可読値と、ウェブブラウザでのレンダリングのための人間可読値を提供します。この場合、value属性で使用されるフォーマットは、使用しているマイクロフォーマットやマイクロデータの語彙によって決まります。
しかし、この要素はページ内のスクリプトと組み合わせて使用することもできます。スクリプトが人間可読値とともにリテラル値を格納する場合です。このような場合、使用されるフォーマットはスクリプトのニーズにのみ依存します(data-*属性もこのような状況で役立つ場合があります)。
すべての現在のエンジンでサポートされています。
value
IDL属性は、同じ名前のコンテンツ属性を反映する必要があります。
ここでは、テーブルのソート JavaScript ライブラリが、テキスト形式の列と分解形式の列の両方に表示された数字に対して、列ごとのソート機能を提供できるように、data
要素を使用して数値がエンコードされた短いテーブルを示します。
< script src = "sortable.js" ></ script >
< table class = "sortable" >
< thead > < tr > < th > Game < th > Corporations < th > Map Size
< tbody >
< tr > < td > 1830 < td > < data value = "8" > Eight</ data > < td > < data value = "93" > 19+74 hexes (93 total)</ data >
< tr > < td > 1856 < td > < data value = "11" > Eleven</ data > < td > < data value = "99" > 12+87 hexes (99 total)</ data >
< tr > < td > 1870 < td > < data value = "10" > Ten</ data > < td > < data value = "149" > 4+145 hexes (149 total)</ data >
</ table >
time 要素すべての現在のエンジンでサポートされています。
すべての現在のエンジンでサポートされています。
datetime — 機械が読み取れる値
[Exposed =Window ]
interface HTMLTimeElement : HTMLElement {
[HTMLConstructor ] constructor ();
[CEReactions ] attribute DOMString dateTime ;
};
time 要素は、その内容と datetime
属性にあるその内容の機械可読形式を表します。内容の種類は、以下に説明されるさまざまな日付、時刻、タイムゾーンオフセット、および期間に限定されます。
datetime
属性は存在するかもしれません。存在する場合、その値は要素の内容を機械が読み取れる形式で表したものでなければなりません。
time 要素が datetime
コンテンツ属性を持たない場合、その要素には子要素を持つことはできません。
time 要素の datetime 値 は、要素の datetime
コンテンツ属性の値であり、存在する場合、そうでなければ 子テキストコンテンツ です。
time 要素の datetime 値 は、以下のいずれかの構文に一致しなければなりません。
< time > 2011-11</ time >
< time > 2011-11-18</ time >
< time > 11-18</ time >
< time > 14:54</ time >
< time > 14:54:39</ time >
< time > 14:54:39.929</ time >
< time > 2011-11-18T14:54</ time >
< time > 2011-11-18T14:54:39</ time >
< time > 2011-11-18T14:54:39.929</ time >
< time > 2011-11-18 14:54</ time >
< time > 2011-11-18 14:54:39</ time >
< time > 2011-11-18 14:54:39.929</ time >
日付のある時刻ですが、タイムゾーンオフセットがないものは、各タイムゾーンで一日を通して同じ特定の時刻に観察されるイベントを指定するのに役立ちます。たとえば、2020 年の新年は、すべてのタイムゾーンで 2020-01-01 00:00 に祝われますが、すべてのタイムゾーンで同時に祝われるわけではありません。すべてのタイムゾーンで同時に発生するイベントの場合、たとえばビデオ会議のような会議には、有効なグローバルの日付と時刻の文字列 の方が役立つ可能性があります。
< time > Z</ time >
< time > +0000</ time >
< time > +00:00</ time >
< time > -0800</ time >
< time > -08:00</ time >
日付のない時刻(または複数の日付で繰り返されるイベントを指す時刻)の場合、タイムゾーンオフセットを指定するよりも、その時刻を制御する地理的位置を指定する方が通常は役立ちます。なぜなら、地理的位置はサマータイムによってタイムゾーンオフセットを変更するからです。場合によっては、地理的位置がタイムゾーンを変更することさえあります。たとえば、2011 年の終わりにサモアで発生したように、タイムゾーンの境界が引き直された場合などです。各タイムゾーンの境界とそれぞれのゾーン内で適用されるルールを記述するタイムゾーンデータベースと呼ばれるデータベースが存在します。[TZDATABASE]
< time > 2011-11-18T14:54Z</ time >
< time > 2011-11-18T14:54:39Z</ time >
< time > 2011-11-18T14:54:39.929Z</ time >
< time > 2011-11-18T14:54+0000</ time >
< time > 2011-11-18T14:54:39+0000</ time >
< time > 2011-11-18T14:54:39.929+0000</ time >
< time > 2011-11-18T14:54+00:00</ time >
< time > 2011-11-18T14:54:39+00:00</ time >
< time > 2011-11-18T14:54:39.929+00:00</ time >
< time > 2011-11-18T06:54-0800</ time >
< time > 2011-11-18T06:54:39-0800</ time >
< time > 2011-11-18T06:54:39.929-0800</ time >
< time > 2011-11-18T06:54-08:00</ time >
< time > 2011-11-18T06:54:39-08:00</ time >
< time > 2011-11-18T06:54:39.929-08:00</ time >
日付とタイムゾーンオフセットを含む時刻は、特定のイベント、または特定の地理的位置に固定されていない仮想イベントの繰り返しを指定するのに役立ちます。たとえば、隕石の衝突の正確な時刻や、毎日 1400 UTC に開催される一連の会議などです。地理的な場所のタイムゾーンオフセットによって正確な時刻が異なるイベントの場合、有効なローカルの日付と時刻の文字列 とその地理的位置を組み合わせた方が役立つ可能性があります。
< time > 2011-W47</ time >
< time > 2011</ time >
< time > 0001</ time >
< time > PT4H18M3S</ time >
< time > 4h 18m 3s</ time >
要素の内容の機械可読の同等物は、要素のdatetime 値から次のアルゴリズムを使用して取得しなければなりません。
要素のdatetime 値から月文字列を解析して月が返された場合、それが機械可読の同等物です;終了。
要素のdatetime 値から日付文字列を解析して日付が返された場合、それが機械可読の同等物です;終了。
要素のdatetime 値から年なし日付文字列を解析して年なし日付が返された場合、それが機械可読の同等物です;終了。
要素のdatetime 値から時間文字列を解析して時間が返された場合、それが機械可読の同等物です;終了。
要素のdatetime 値からローカル日時文字列を解析してローカル日時が返された場合、それが機械可読の同等物です;終了。
要素のdatetime 値からタイムゾーンオフセット文字列を解析してタイムゾーンオフセットが返された場合、それが機械可読の同等物です;終了。
要素のdatetime 値からグローバル日時文字列を解析してグローバル日時が返された場合、それが機械可読の同等物です;終了。
要素のdatetime 値から週文字列を解析して週が返された場合、それが機械可読の同等物です;終了。
要素のdatetime 値が、少なくとも一つのU+0030 DIGIT ZERO(0)以外のASCII数字のみで構成されている場合、機械可読の同等物はその数字の十進数解釈であり、年を表します;終了。
要素のdatetime 値から期間文字列を解析して期間が返された場合、それが機械可読の同等物です;終了。
機械可読の同等物はありません。
上記のアルゴリズムは、任意の文字列sに対して、1つのアルゴリズムだけが値を返すように設計されているはずです。より効率的なアプローチは、これらのデータ型を一度に解析する単一のアルゴリズムを作成することかもしれません。そのようなアルゴリズムを開発することは読者に委ねられます。
すべての現在のエンジンでサポートされています。
dateTime
IDL属性は、要素のdatetime内容属性を反映する必要があります。
time
要素は、たとえばマイクロフォーマットで日付をエンコードするために使用できます。以下は、time 要素を使用して hCalendar
のバリアントを用いたイベントをエンコードする仮想的な方法を示しています。
< div class = "vevent" >
< a class = "url" href = "http://www.web2con.com/" > http://www.web2con.com/</ a >
< span class = "summary" > Web 2.0 Conference</ span > :
< time class = "dtstart" datetime = "2005-10-05" > October 5</ time > -
< time class = "dtend" datetime = "2005-10-07" > 7</ time > ,
at the < span class = "location" > Argent Hotel, San Francisco, CA</ span >
</ div >
ここでは、架空のマイクロデータ語彙が Atom 語彙に基づいて使用されており、time
要素を使用してブログ投稿の発行日をマークアップしています。
< article itemscope itemtype = "https://n.example.org/rfc4287" >
< h1 itemprop = "title" > Big tasks</ h1 >
< footer > Published < time itemprop = "published" datetime = "2009-08-29" > two days ago</ time > .</ footer >
< p itemprop = "content" > Today, I went out and bought a bike for my kid.</ p >
</ article >
この例では、別の記事の発行日が schema.org マイクロデータ語彙を使用して time 要素でマークアップされています。
< article itemscope itemtype = "http://schema.org/BlogPosting" >
< h1 itemprop = "headline" > Small tasks</ h1 >
< footer > Published < time itemprop = "datePublished" datetime = "2009-08-30" > yesterday</ time > .</ footer >
< p itemprop = "articleBody" > I put a bike bell on her bike.</ p >
</ article >
以下のスニペットでは、time 要素を使用して
ISO8601 形式の日付をエンコードし、後でスクリプトによって処理されます。
< p > Our first date was < time datetime = "2006-09-23" > a Saturday</ time > .</ p >
この2番目のスニペットでは、値に時刻が含まれています:
< p > We stopped talking at < time datetime = "2006-09-24T05:00-07:00" > 5am the next morning</ time > .</ p >
ページに読み込まれるスクリプト(したがって time
要素を使用して日付や時刻をマークアップするページの内部規約に精通している)は、ページ全体をスキャンしてすべての time
要素を調べ、日付と時刻のインデックスを作成できます。
たとえば、この要素は、「Friday」という文字列に「2011年11月18日」が対応することを伝えます:
Today is < time datetime = "2011-11-18" > Friday</ time > .
この例では、太平洋標準時 (PST) の特定の時間が指定されています:
Your next meeting is at < time datetime = "2011-11-18T15:00-08:00" > 3pm</ time > .
code
要素すべての最新エンジンでサポートされています。
HTMLElementを使用します。
code
要素は、コンピュータコードの断片を表します。これは、XML要素名、ファイル名、コンピュータプログラム、またはコンピュータが認識する他の文字列である可能性があります。
コンピュータコードのマークアップに使用される言語を示す正式な方法はありません。
使用する言語を code
要素にマークしたい著者は、たとえば構文強調スクリプトが適切なルールを使用できるように、
class 属性を使用できます。
たとえば、要素に「language-」というプレフィックスを付けたクラスを追加します。
次の例は、段落内で要素名やコンピュータコードをマークアップするためにこの要素をどのように使用できるかを示しています。
< p > The < code > code</ code > element represents a fragment of computer
code.</ p >
< p > When you call the < code > activate()</ code > method on the
< code > robotSnowman</ code > object, the eyes glow.</ p >
< p > The example below uses the < code > begin</ code > keyword to indicate
the start of a statement block. It is paired with an < code > end</ code >
keyword, which is followed by the < code > .</ code > punctuation character
(full stop) to indicate the end of the program.</ p >
次の例は、pre
および code
要素を使用してコードブロックをマークアップする方法を示しています。
< pre >< code class = "language-pascal" > var i: Integer;
begin
i := 1;
end.</ code ></ pre >
その例では、使用言語を示すためにクラスが使用されています。
詳細については、pre
要素を参照してください。
var
要素すべての最新エンジンでサポートされています。
HTMLElementを使用します。
var
要素は、変数を表します。これは、数学的表現やプログラミングの文脈での実際の変数、定数を表す識別子、物理量を識別する記号、関数のパラメーター、または単に文章中でプレースホルダーとして使用される用語である可能性があります。
次の段落では、文字「n」が文章中で変数として使用されています:
< p > If there are < var > n</ var > pipes leading to the ice
cream factory then I expect at < em > least</ em > < var > n</ var >
flavors of ice cream to be available for purchase!</ p >
数学に関しては、特に単純な表現を超えるものについては、MathML の方が適しています。
ただし、var 要素は、
MathML 表現で言及される特定の変数を指すために使用できます。
この例では、方程式が示されており、その方程式の変数を参照する凡例が付いています。
表現自体は MathML でマークアップされていますが、変数は var 要素を使用して凡例に記載されています。
< figure >
< math >
< mi > a</ mi >
< mo > =</ mo >
< msqrt >
< msup >< mi > b</ mi >< mn > 2</ mn ></ msup >
< mi > +</ mi >
< msup >< mi > c</ mi >< mn > 2</ mn ></ msup >
</ msqrt >
</ math >
< figcaption >
ピタゴラスの定理を使用して、三角形の斜辺 < var > a</ var > を解きます。
三角形の他の辺は < var > b</ var > および < var > c</ var > です。
</ figcaption >
</ figure >
ここでは、質量エネルギー等価性を説明する方程式が文中で使用されており、その方程式に含まれる
変数や定数をマークアップするために var
要素が使用されています。
< p > Then she turned to the blackboard and picked up the chalk. After a few moment's
thought, she wrote < var > E</ var > = < var > m</ var > < var > c</ var >< sup > 2</ sup > . The teacher
looked pleased.</ p >
samp
要素すべての最新エンジンでサポートされています。
HTMLElementを使用します。
samp 要素は
他のプログラムやコンピュータシステムからのサンプルまたは引用された出力を表します。
詳細については、pre 要素および
kbd 要素を参照してください。
この要素は、ウェブアプリケーションで即時出力を提供するために使用できる
output 要素と対比することができます。
この例では、samp
要素がインラインで使用されています:
< p > The computer said < samp > Too much cheese in tray
two</ samp > but I didn't know what that meant.</ p >
2つ目の例は、コンソールプログラムのサンプル出力のブロックを示しています。ネストされた
samp 要素と kbd
要素を使用することで、スタイルシートを使用してサンプル出力の特定の要素をスタイリングできます。
さらに詳細なマークアップで注釈が付けられている部分もあり、非常に精密なスタイリングが可能です。この目的を達成するために、span 要素が使用されています。
< pre >< samp >< span class = "prompt" > jdoe@mowmow:~$</ span > < kbd > ssh demo.example.com</ kbd >
Last login: Tue Apr 12 09:10:17 2005 from mowmow.example.com on pts/1
Linux demo 2.6.10-grsec+gg3+e+fhs6b+nfs+gr0501+++p3+c4a+gr2b-reslog-v6.189 #1 SMP Tue Feb 1 11:22:36 PST 2005 i686 unknown
< span class = "prompt" > jdoe@demo:~$</ span > < span class = "cursor" > _</ span ></ samp ></ pre >
3つ目の例では、入力とその出力が示されています。この例では
code 要素と samp 要素の両方が使用されています。
< pre >
< code class = "language-javascript" > console.log(2.3 + 2.4)</ code >
< samp > 4.699999999999999</ samp >
</ pre >
kbd
要素すべての最新エンジンでサポートされています。
HTMLElementを使用します。
kbd
要素は、ユーザー入力(通常はキーボード入力、ただし音声コマンドなどの他の入力も表すことができます)を表します。
kbd 要素が samp
要素内にネストされている場合、それはシステムによってエコーされた入力を表します。
kbd 要素が 含む samp
要素は、システム出力に基づく入力を表します。たとえば、メニュー項目を呼び出す場合などです。
kbd 要素が別の kbd
要素内にネストされている場合、それは入力メカニズムに適した実際のキーまたは他の単一の入力単位を表します。
ここでは、kbd
要素が押すべきキーを示すために使用されています:
< p > To make George eat an apple, press < kbd >< kbd > Shift</ kbd > + < kbd > F3</ kbd ></ kbd ></ p >
2つ目の例では、ユーザーに特定のメニュー項目を選択するよう指示しています。外側の
kbd 要素は入力ブロックをマークアップし、内側の
kbd 要素は入力の各ステップを表し、それらの中の
samp
要素は、システムによって表示されているメニューラベルなどに基づく入力を示しています:
< p > To make George eat an apple, select
< kbd >< kbd >< samp > File</ samp ></ kbd > |< kbd >< samp > Eat Apple...</ samp ></ kbd ></ kbd >
</ p >
このような精密さは必ずしも必要ではありません。次の例でも問題ありません:
< p > To make George eat an apple, select < kbd > File | Eat Apple...</ kbd ></ p >
sub および sup 要素
すべての最新エンジンでサポートされています。
すべての最新エンジンでサポートされています。
sub
要素: 著者向け; 実装者向け。
sup
要素: 著者向け; 実装者向け。
HTMLElement を使用します。
sup
要素は上付き文字を、sub
要素は下付き文字を 表します。
これらの要素は、特定の意味を持つ書体上の慣習をマークアップするためにのみ使用する必要があり、単なる書体上のプレゼンテーションのために使用してはなりません。たとえば、LaTeX ドキュメント作成システムの名前で sub および
sup
要素を使用するのは不適切です。一般的に、これらの要素を使用しないと、コンテンツの意味が変わる場合にのみ使用する必要があります。
特定の言語では、上付き文字は一部の略語の書体上の慣習の一部です。
< p > Their names are
< span lang = "fr" >< abbr > M< sup > lle</ sup ></ abbr > Gwendoline</ span > and
< span lang = "fr" >< abbr > M< sup > me</ sup ></ abbr > Denise</ span > .</ p >
sub
要素は、下付き文字を持つ変数に対して var
要素内で使用できます。
ここでは、sub
要素が、変数のファミリー内の変数を識別する下付き文字を表すために使用されています:
< p > The coordinate of the < var > i</ var > th point is
(< var > x</ sub >< var > i</ var ></ sub ></ var > , < var > y</ sub >< var > i</ var ></ sub ></ var > ).
For example, the 10th point has coordinate
(< var > x</ sub > 10</ sub ></ var > , < var > y</ sub > 10</ sub ></ var > ).</ p >
数学の式では、下付き文字と上付き文字がよく使用されます。著者は、数学をマークアップするために MathML の使用を推奨されますが、詳細な数学マークアップが不要な場合は、sub および
sup
を使用することもできます。 [MATHML]
< var > E</ var > =< var > m</ var >< var > c</ var >< sup > 2</ sup >
f(< var > x</ var > , < var > n</ var > ) = log< sub > 4</ sub >< var > x</ var ></ sup >< var > n</ var ></ sup >
i
要素すべての最新エンジンでサポートされています。
HTMLElement を使用します。
i
要素は、異なる声や雰囲気、あるいは通常の文章とは異なる品質を示す方法で、本文から区別されたテキストの範囲を表します。例えば、分類学的指定、技術用語、他の言語の慣用句、翻字、考え、西洋のテキストでの船名などです。
メインテキストとは異なる言語の用語には、lang 属性(または、XML では lang 属性を XML 名前空間で使用)を注釈する必要があります。
以下の例は、i 要素の使用例を示しています:
< p > The < i class = "taxonomy" > Felis silvestris catus</ i > is cute.</ p >
< p > The term < i > prose content</ i > is defined above.</ p >
< p > There is a certain < i lang = "fr" > je ne sais quoi</ i > in the air.</ p >
次の例では、夢のシーケンスが i 要素を使ってマークアップされています。
< p > Raymond tried to sleep.</ p >
< p >< i > The ship sailed away on Thursday</ i > , he
dreamt. < i > The ship had many people aboard, including a beautiful
princess called Carey. He watched her, day-in, day-out, hoping she
would notice him, but she never did.</ i ></ p >
< p >< i > Finally one night he picked up the courage to speak with
her—</ i ></ p >
< p > Raymond woke with a start as the fire alarm rang out.</ p >
著者は、class 属性を i
要素に使用して、この要素が使用される理由を特定することができます。たとえば、特定の使用スタイル(夢のシーケンスや分類学的用語など)が後日変更される場合に、著者がドキュメント全体(または関連する一連のドキュメント)を調べて各使用を注釈する必要がなくなります。
著者は、i
要素よりも適用できる他の要素を検討することをお勧めします。たとえば、ストレスの強調をマークアップするための em 要素や、用語の定義インスタンスをマークアップするための dfn 要素などです。
スタイルシートを使用して、他の要素と同様に i
要素を再スタイル化できます。したがって、i
要素内のコンテンツが必ずしもイタリック体で表示されるわけではありません。
b
要素すべての最新エンジンでサポートされています。
HTMLElement を使用します。
b
要素は、特別な重要性を付与せずに、実用的な目的で注意が向けられているテキスト範囲を表します。例えば、文書の要約におけるキーワード、レビューでの製品名、インタラクティブなテキスト駆動型ソフトウェアでのアクション可能な言葉、または記事のリード文などです。
次の例は、b
要素を使用してキーワードを強調表示する例を示していますが、重要性を付与するためのマークアップではありません:
< p > The < b > frobonitor</ b > and < b > barbinator</ b > components are fried.</ p >
次の例では、テキストアドベンチャーのオブジェクトを b
要素を使用して特別なものとして強調しています。
< p > You enter a small room. Your < b > sword</ b > glows
brighter. A < b > rat</ b > scurries past the corner wall.</ p >
別の例として、b
要素を使用してリード文をマークアップするのが適切です。次の例では、BBC の記事
がどのようにマークアップされるかを示しています:
< article >
< h2 > Kittens 'adopted' by pet rabbit</ h2 >
< p >< b class = "lede" > Six abandoned kittens have found an
unexpected new mother figure — a pet rabbit.</ b ></ p >
< p > Veterinary nurse Melanie Humble took the three-week-old
kittens to her Aberdeen home.</ p >
[...]
i 要素と同様に、著者は class 属性を b
要素に使用して、後日スタイルが変更される場合に備えて、なぜこの要素が使用されているのかを特定することができます。これにより、ドキュメント全体を手動で注釈する必要がなくなります。
b
要素は、他のより適切な要素がない場合の最後の手段として使用するべきです。特に、見出しには h1
から h6
の要素を使用し、強調する場合には em 要素を使用し、重要性を示す場合には
strong
要素を使用し、テキストをマークまたはハイライトする場合には mark
要素を使用すべきです。
次の使用例は不正確な使用です:
< p >< b > WARNING!</ b > Do not frob the barbinator!</ p >
スタイルシートを使用して、b
要素を他の要素と同様に再スタイル化することができます。したがって、b
要素内のコンテンツが必ずしも太字で表示されるわけではありません。
u
要素すべての最新エンジンでサポートされています。
HTMLElement を使用します。
u 要素は、明示的にレンダリングされるが、非テキストの注釈を持つテキスト範囲を表します。例えば、中国語の名前を表すための文字 (中国の固有名詞マーク)
や、綴り間違いを示すためのラベル付けなどがあります。
ほとんどの場合、他の要素を使用する方が適切です。例えば、強調を示す場合には em
要素を使用すべきです。キーワードやフレーズをマークする場合には、状況に応じて b
要素や mark
要素を使用すべきです。書籍のタイトルをマークする場合には cite
要素を使用すべきです。明示的なテキスト注釈をラベル付けする場合には ruby
要素を使用すべきです。技術用語、分類学的指定、翻字、考え、または西洋のテキストにおける船名をラベル付けする場合には i 要素を使用すべきです。
u
要素の視覚的なデフォルトのレンダリングは、ハイパーリンクの従来のレンダリング (下線) と競合します。著者は、u
要素がハイパーリンクと混同される可能性がある場合には、使用を避けることが推奨されます。
この例では、u 要素を使用して単語を誤字としてマークしています:
< p > The < u > see</ u > is full of fish.</ p >
mark
要素すべての最新エンジンでサポートされています。
HTMLElement を使用します。
mark 要素は、1
つのドキュメント内で他の文脈において関連性のあるために参照または注釈目的でマークまたはハイライトされたテキスト範囲を表します。引用やその他の文章ブロックで使用される場合、それは最初に存在しなかったハイライトを示しており、元の著者が元々書いたときには重要とは考えられなかったテキスト部分に読者の注意を引くために追加されたことを意味します。ドキュメントの主要な文章で使用される場合、それはユーザーの現在の活動に関連する可能性が高い部分をハイライトすることを意味します。
次の例では、mark
要素を使用して特定の引用部分に注意を引く方法を示します:
< p lang = "en-US" > Consider the following quote:</ p >
< blockquote lang = "en-GB" >
< p > Look around and you will find, no-one's really
< mark > colour</ mark > blind.</ p >
</ blockquote >
< p lang = "en-US" > As we can tell from the < em > spelling</ em > of the word,
the person writing this quote is clearly not American.</ p >
(この要素を綴り間違いとしてマークすることが目的であった場合、u
要素、おそらくクラスを付与する方が適切でしょう。)
もう一つの例では、mark
要素が検索文字列に一致する文書の一部をハイライトする方法を示しています。誰かが文書を検索し、サーバーがユーザーが「kitten」という単語を検索していることを知っている場合、サーバーは次のように段落を変更して文書を返すかもしれません:
< p > I also have some < mark > kitten</ mark > s who are visiting me
these days. They're really cute. I think they like my garden! Maybe I
should adopt a < mark > kitten</ mark > .</ p >
次のスニペットでは、段落のテキストがコードの特定の部分に言及しています。
< p > The highlighted part below is where the error lies:</ p >
< pre >< code > var i: Integer;
begin
i := < mark > 1.1</ mark > ;
end.</ code ></ pre >
これは、構文ハイライトとは別物であり、構文ハイライトには span
を使用するのが適しています。両方を組み合わせると、次のようになります:
< p > The highlighted part below is where the error lies:</ p >
< pre >< code >< span class = keyword > var</ span > < span class = ident > i</ span > : < span class = type > Integer</ span > ;
< span class = keyword > begin</ span >
< span class = ident > i</ span > := < span class = literal >< mark > 1.1</ mark ></ span > ;
< span class = keyword > end</ span > .</ code ></ pre >
以下の例では、元々強調されていなかった引用文の一部を強調するために mark
を使用する方法を示しています。この例では、一般的な印刷の慣例により、引用文内の mark
要素がイタリック体で表示されるようにスタイルが明示的に設定されています。
< style >
blockquote mark , q mark {
font : inherit ; font-style : italic ;
text-decoration : none ;
background : transparent ; color : inherit ;
}
. bubble em {
font : inherit ; font-size : larger ;
text-decoration : underline ;
}
</ style >
< article >
< h1 > She knew</ h1 >
< p > Did you notice the subtle joke in the joke on panel 4?</ p >
< blockquote >
< p class = "bubble" > I didn't < em > want</ em > to believe. < mark > Of course
on some level I realized it was a known-plaintext attack.</ mark > But I
couldn't admit it until I saw for myself.</ p >
</ blockquote >
< p > (Emphasis mine.) I thought that was great. It's so pedantic, yet it
explains everything neatly.</ p >
</ article >
なお、この例では em
要素は引用文の元のテキストの一部であり、mark
要素はコメントのために一部をハイライトしていることに注意してください。
次の例では、テキストの一部分の 重要性 を示す (strong) のと、テキストの
関連性 を示す (mark)
の違いを示しています。これは教科書の抜粋で、試験に関連する部分がハイライトされています。安全警告は重要であるにもかかわらず、試験には関連していないようです。
< h3 > Wormhole Physics Introduction</ h3 >
< p >< mark > A wormhole in normal conditions can be held open for a
maximum of just under 39 minutes.</ mark > Conditions that can increase
the time include a powerful energy source coupled to one or both of
the gates connecting the wormhole, and a large gravity well (such as a
black hole).</ p >
< p >< mark > Momentum is preserved across the wormhole. Electromagnetic
radiation can travel in both directions through a wormhole,
but matter cannot.</ mark ></ p >
< p > When a wormhole is created, a vortex normally forms.
< strong > Warning: The vortex caused by the wormhole opening will
annihilate anything in its path.</ strong > Vortexes can be avoided when
using sufficiently advanced dialing technology.</ p >
< p >< mark > An obstruction in a gate will prevent it from accepting a
wormhole connection.</ mark ></ p >
bdi要素すべての現行エンジンでサポートされています。
dir グローバル属性は、この要素に特有の意味を持ちます。
HTMLElement を使用します。
bdi要素は、双方向テキストの書式設定のために、その周囲から分離されるテキストの範囲を表します。[BIDI]
dir グローバル属性は、この要素においては auto
がデフォルトであり、他の要素のように親要素から継承されることはありません。
この要素は双方向アルゴリズムに関するレンダリング要件を持っています。
この要素は、方向性が不明なユーザー生成コンテンツを埋め込む際に特に役立ちます。
この例では、ユーザー名とそのユーザーが投稿した件数が表示されます。もしbdi要素が使用されていなければ、アラビア語のユーザー名がテキストを混乱させてしまいます(双方向アルゴリズムにより、コロンと数字の「3」が「User」の隣に配置され、「posts」の隣に配置されるべきではありません)。
< ul >
< li > User < bdi > jcranmer</ bdi > : 12 posts.
< li > User < bdi > hober</ bdi > : 5 posts.
< li > User < bdi > إيان</ bdi > : 3 posts.
</ ul >
bdi
要素を使用すると、ユーザー名は期待通りに動作します。
bdi要素がb要素に置き換えられると、ユーザー名が双方向アルゴリズムを混乱させ、3番目の箇条書きは「User
3 :」と表示され、その後にアラビア語の名前(右から左)が続き、「posts」とピリオドが続きます。bdo要素すべての最新エンジンでサポートされています。
dir グローバル属性は、この要素に特有の意味を持ちます。
HTMLElement を使用します。
bdo要素は、子要素に対する明示的なテキストの方向性フォーマット制御を表します。これにより、著者はUnicode双方向アルゴリズムをオーバーライドし、明示的に方向性のオーバーライドを指定できます。[BIDI]
著者は、この要素にdir属性を指定し、左から右へのオーバーライドを指定するためにltr値を指定し、右から左へのオーバーライドを指定するためにrtl値を指定する必要があります。auto値は指定してはなりません。
この要素は双方向アルゴリズムに関するレンダリング要件を持っています。
span要素すべての最新エンジンでサポートされています。
すべての最新エンジンでサポートされています。
[Exposed =Window ]
interface HTMLSpanElement : HTMLElement {
[HTMLConstructor ] constructor ();
};
span要素自体は何も意味しませんが、グローバル属性と一緒に使用すると便利です。例としてclass、lang、またはdirがあります。この要素はその子要素を表します。
この例では、コードフラグメントが span 要素と class
属性を使用してマークアップされており、CSSからキーワードや識別子を色分けできるようにしています。
< pre >< code class = "lang-c" >< span class = "keyword" > for</ span > (< span class = "ident" > j</ span > = 0; < span class = "ident" > j</ span > < 256; < span class = "ident" > j</ span > ++) {
< span class = "ident" > i_t3</ span > = (< span class = "ident" > i_t3</ span > & 0x1ffff) | (< span class = "ident" > j</ span > << 17);
< span class = "ident" > i_t6</ span > = (((((((< span class = "ident" > i_t3</ span > >> 3) ^ < span class = "ident" > i_t3</ span > ) >> 1) ^ < span class = "ident" > i_t3</ span > ) >> 8) ^ < span class = "ident" > i_t3</ span > ) >> 5) & 0xff;
< span class = "keyword" > if</ span > (< span class = "ident" > i_t6</ span > == < span class = "ident" > i_t1</ span > )
< span class = "keyword" > break</ span > ;
}</ code ></ pre >
br要素
すべての最新エンジンでサポートされています。
すべての最新エンジンでサポートされています。
[Exposed =Window ]
interface HTMLBRElement : HTMLElement {
[HTMLConstructor ] constructor ();
// 旧メンバーも含む
};
改行は通常、視覚メディアでは次のテキストを新しい行に物理的に移動させることで表されますが、スタイルシートやユーザーエージェントは、たとえば緑色の点として、または追加のスペースとして改行をレンダリングすることも同様に正当です。
br要素は、詩や住所のように、実際にコンテンツの一部としての改行にのみ使用されるべきです。
次の例は、br要素の正しい使用法です:
< p > P. Sherman< br >
42 Wallaby Way< br >
Sydney</ p >
br要素は、段落内で主題別グループを分離するために使用されるべきではありません。
次の例は、br要素を誤用した非準拠の例です:
< p >< a ...> 34件のコメント.</ a >< br >
< a ...> コメントを追加.</ a ></ p >
< p >< label > 名前: < input name = "name" ></ label >< br >
< label > 住所: < input name = "address" ></ label ></ p >
次の正しい例は、上記の代替として使用できます:
< p >< a ...> 34件のコメント.</ a ></ p >
< p >< a ...> コメントを追加.</ a ></ p >
< p >< label > 名前: < input name = "name" ></ label ></ p >
< p >< label > 住所: < input name = "address" ></ label ></ p >
段落がbr要素だけで構成されている場合、それはプレースホルダーとしての空白行を表します(例:
テンプレートでの使用)。このような空白行は、プレゼンテーション目的で使用してはなりません。
br要素内のコンテンツは、周囲のテキストの一部と見なされるべきではありません。
この要素は双方向アルゴリズムに関連するレンダリング要件を持ちます。
wbr要素すべての最新エンジンでサポートされています。
HTMLElementを使用します。
次の例では、誰かが効果を狙って、1つの長い単語として書かれた何かを引用しています。ただし、テキストが読みやすい形で改行できるようにするために、引用内の個々の単語がwbr要素で区切られています。
< p > So then she pointed at the tiger and screamed
"there< wbr > is< wbr > no< wbr > way< wbr > you< wbr > are< wbr > ever< wbr > going< wbr > to< wbr > catch< wbr > me"!</ p >
wbr要素内のコンテンツは、周囲のテキストの一部と見なされるべきではありません。
var wbr = document. createElement( "wbr" );
wbr. textContent = "This is wrong" ;
document. body. appendChild( wbr);
この要素は双方向アルゴリズムに関連するレンダリング要件を持ちます。
このセクションは規範的ではありません。
| 要素 | 目的 | 例 |
|---|---|---|
a
| ハイパーリンク |
|
em
| 強調 |
|
strong
| 重要性 |
|
small
| サイドコメント |
|
s
| 不正確なテキスト |
|
cite
| 作品のタイトル |
|
q
| 引用 |
|
dfn
| 定義 |
|
abbr
| 略語 |
|
ruby, rt, rp
| ルビ注釈 |
|
data
| 機械可読の値 |
|
time
| 日付や時間の機械可読の値 |
|
code
| コンピュータコード |
|
var
| 変数 |
|
samp
| コンピュータの出力 |
|
kbd
| ユーザー入力 |
|
sub
| 下付き文字 |
|
sup
| 上付き文字 |
|
i
| 別の声 |
|
b
| キーワード |
|
u
| 注釈 |
|
mark
| ハイライト |
|
bdi
| テキストの方向性の分離 |
|
bdo
| テキストの方向性の書式設定 |
|
span
| その他 |
|
br
| 改行 |
|
wbr
| 改行可能な位置 |
|
リンクは、a、area、form、およびlink要素によって作成される概念的な構成です。これらは、現在のドキュメントと他のリソースとの間に接続を表します。HTMLには3種類のリンクがあります:
これらは現在のドキュメントを補完するために使用されるリソースへのリンクであり、一般的にユーザーエージェントによって自動的に処理されます。すべての外部リソースへのリンクは、リソースの取得と処理を説明するリソースを取得して処理するアルゴリズムを持っています。
これらは他のリソースへのリンクであり、ユーザーエージェントによって一般的にユーザーに公開され、ユーザーがこれらのリソースにナビゲートできるようにします。例えば、ブラウザでそれらを訪問したり、ダウンロードしたりすることができます。
これらは現在のドキュメント内のリソースへのリンクであり、これらのリソースに特別な意味や動作を与えるために使用されます。
link要素にhref属性およびrel属性がある場合、rel属性のキーワードに対してリンクが作成されなければなりません。
同様に、aおよびarea要素にhref属性およびrel属性がある場合、リンクはリンクタイプセクションで定義されたキーワードに対しても作成されなければなりません。
同様に、form要素にrel属性がある場合、rel属性のキーワードに対してリンクが作成されなければなりません。
ハイパーリンクには、そのハイパーリンクの処理セマンティクスを変更する1つまたは複数のハイパーリンク注釈を持つことができます。
a および area
要素によって作成されるリンクa および area 要素の
href 属性は、有効なURL(スペースで囲まれている場合もあり)でなければなりません。
href
属性は必須ではありません。a および area 要素が
href
属性を持たない場合、それらはハイパーリンクを作成しません。
target
属性が存在する場合、その値は 有効なナビゲーブルターゲット名またはキーワード
でなければなりません。これは使用されるナビゲーブル
の名前を指定します。ユーザーエージェントは、ハイパーリンクをたどる際にこの名前を使用します。
download
属性が存在する場合、著者がそのハイパーリンクを リソースのダウンロード
に使用する意図があることを示します。この属性には値を持たせることができます。値が指定されている場合、その値はローカルファイルシステムでリソースをラベル付けするために推奨されるデフォルトのファイル名を指定します。許可される値に制限はありませんが、ほとんどのファイルシステムにはファイル名でサポートされる句読点に制限があるため、ユーザーエージェントはファイル名を適宜調整する可能性があることに注意が必要です。
Support in all current engines.
ping
属性が存在する場合、ユーザーがハイパーリンクをたどる際に通知を受け取りたいリソースのURLを指定します。値は 空白で区切られたトークンのセット でなければならず、それぞれが 有効な非空のURL
でなければならず、その スキーム は HTTP(S) スキーム でなければなりません。この値はユーザーエージェントが ハイパーリンク監査 に使用します。
rel 属性は、a 要素と area
要素に対して、どの種類のリンクを作成するかを制御します。この属性の値は 一意の空白で区切られたトークンの非順序セット
でなければなりません。許可されるキーワードとその意味 は以下に定義されています。
rel の サポートされているトークン は、HTML リンクタイプ
に定義されたキーワードであり、a
要素と area
要素で許可されているもので、処理モデルに影響を与え、ユーザーエージェントによってサポートされています。可能な サポートされているトークン は noreferrer、noopener、および
opener
です。rel
の サポートされているトークン
には、ユーザーエージェントが処理モデルを実装しているこのリストのトークンのみが含まれている必要があります。
rel
属性にはデフォルト値がありません。属性が省略されているか、属性内のいずれの値もユーザーエージェントによって認識されない場合、文書はリンク先リソースとの特定の関係を持たず、2つの間にハイパーリンクが存在するだけです。
hreflang
属性は、a 要素が ハイパーリンク
を作成する場合、リンク先リソースの言語を指定します。これは純粋に助言的なものです。値は有効な BCP 47 言語タグでなければなりません。[BCP47]
ユーザーエージェントは、この属性を権威あるものと見なしてはなりません。リソースを取得すると、ユーザーエージェントは、リソースに関連付けられた言語情報のみを使用して、その言語を判断し、リンクに含まれるメタデータを使用してはなりません。
type
属性が存在する場合、リンクされたリソースの MIME タイプ
を指定します。これは純粋に助言的なものです。値は 有効な MIME
タイプ文字列 でなければなりません。ユーザーエージェントは、リソースにリンクされたメタデータを使用してリソースのタイプを判断してはなりません。
referrerpolicy 属性は 参照ポリシー属性 です。その目的は、参照ポリシー を設定することです。[REFERRERPOLICY]
に従って、ハイパーリンクをたどる 際に使用されます。
a または area 要素の
アクティベーション動作 が呼び出されると、ユーザーエージェントはユーザーに対し、ハイパーリンクがナビゲーションに使用されるか、指定されたリソースがダウンロードされるかの選択肢を与えることがあります。
ユーザーの選好がない場合、要素に download
属性がない場合はデフォルトでナビゲーションが選択され、属性がある場合は指定されたリソースのダウンロードが選択されます。
a または area 要素の
アクティベーション動作 は次の通りです:
要素に href
属性がない場合、何も行いません。
hyperlinkSuffix を null に設定します。
要素が a
要素であり、イベントの target が img
で、ismap
属性が指定されている場合:
x および y を 0 に設定します。
イベントの isTrusted
属性が true に初期化されている場合、クリック位置から画像の左端までの距離を x に設定し、クリック位置から画像の上端までの距離を y
に設定します。
x が負の場合、x を 0 に設定します。
y が負の場合、y を 0 に設定します。
hyperlinkSuffix を U+003F (?), x の値を基数 10 の整数として ASCII 数字で表現したもの、U+002C (,) 、および y の値を基数 10 の整数として ASCII 数字で表現したものの連結として設定します。
ユーザーの関与をイベントの user navigation involvement として設定します。
ユーザーがハイパーリンクをダウンロードすることを希望している場合、userInvolvement を "browser UI"
に設定します。
つまり、ユーザーがダウンロードを特に希望している場合、これは単に "activation"
としてはカウントされません。
element に download
属性がある場合、またはユーザーがハイパーリンクをダウンロードすることを希望している場合、element
によって作成されたハイパーリンクを、hyperlinkSuffix に hyperlinkSuffix を設定し、userInvolvement に userInvolvement を設定して ダウンロード します。
それ以外の場合、ハイパーリンクをフォローします。この際、hyperlinkSuffix を hyperlinkSuffix として、userInvolvement を userInvolvement として設定します。
aおよびarea要素のAPIinterface mixin HTMLHyperlinkElementUtils {
[CEReactions ] stringifier attribute USVString href ;
readonly attribute USVString origin ;
[CEReactions ] attribute USVString protocol ;
[CEReactions ] attribute USVString username ;
[CEReactions ] attribute USVString password ;
[CEReactions ] attribute USVString host ;
[CEReactions ] attribute USVString hostname ;
[CEReactions ] attribute USVString port ;
[CEReactions ] attribute USVString pathname ;
[CEReactions ] attribute USVString search ;
[CEReactions ] attribute USVString hash ;
};
hyperlink.toString()
hyperlink.href
すべての現在のエンジンでサポートされています。
すべての現在のエンジンでサポートされています。
すべての現在のエンジンでサポートされています。
すべての現在のエンジンでサポートされています。
ハイパーリンクの URL を返します。
URL を変更するために設定できます。
hyperlink.origin
すべての現在のエンジンでサポートされています。
すべての現在のエンジンでサポートされています。
ハイパーリンクの URL の起源を返します。
hyperlink.protocol
すべての現在のエンジンでサポートされています。
すべての現在のエンジンでサポートされています。
ハイパーリンクの URL のスキームを返します。
URL のスキームを変更するために設定できます。
hyperlink.username
すべての現在のエンジンでサポートされています。
すべての現在のエンジンでサポートされています。
ハイパーリンクのURLのユーザー名を返します。
設定することで、URLのユーザー名を変更できます。
hyperlink.password
すべての現在のエンジンでサポートされています。
すべての現在のエンジンでサポートされています。
ハイパーリンクのURLのパスワードを返します。
設定することで、URLのパスワードを変更できます。
hyperlink.host
すべての現在のエンジンでサポートされています。
すべての現在のエンジンでサポートされています。
ハイパーリンクのURLのホストとポート(スキームのデフォルトポートと異なる場合)を返します。
設定することで、URLのホストとポートを変更できます。
hyperlink.hostname
すべての現在のエンジンでサポートされています。
すべての現在のエンジンでサポートされています。
ハイパーリンクのURLのドメインを返します。
設定することで、URLのドメインを変更できます。
hyperlink.port
すべての現在のエンジンでサポートされています。
すべての現在のエンジンでサポートされています。
ハイパーリンクの URL のポートを返します。
URL のポートを変更するために設定できます。
hyperlink.pathname
すべての現在のエンジンでサポートされています。
すべての現在のエンジンでサポートされています。
ハイパーリンクの URL のパスを返します。
URL のパスを変更するために設定できます。
hyperlink.search
すべての現在のエンジンでサポートされています。
すべての現在のエンジンでサポートされています。
ハイパーリンクの URL のクエリを返します(非空の場合、先頭の "?" を含む)。
URL のクエリを変更するために設定できます(先頭の "?" は無視されます)。
hyperlink.hash
すべての現在のエンジンでサポートされています。
すべての現在のエンジンでサポートされています。
ハイパーリンクの URL のフラグメントを返します(非空の場合、先頭の "#" を含む)。
URL のフラグメントを変更するために設定できます(先頭の "#" は無視されます)。
HTMLHyperlinkElementUtilsミックスインを実装する要素には、関連付けられたURL(null またはURL)があり、初期状態ではnullです。
HTMLHyperlinkElementUtilsミックスインを実装する要素には、関連付けられたURLを設定するアルゴリズムがあり、次の手順を実行します:
この要素のURLをnullに設定します。
この要素のhrefコンテンツ属性が存在しない場合は、手順を終了します。
この要素のhrefコンテンツ属性の値を、この要素のノードドキュメントに対して、URLのエンコードと解析を行った結果をurlとします。
もしurlが失敗しなかった場合、この要素のURLをurlに設定します。
HTMLHyperlinkElementUtilsミックスインを実装する要素が作成されたとき、またはそれらの要素のhrefコンテンツ属性が設定、変更、または削除されたとき、ユーザーエージェントはURLを設定する必要があります。
これは、blob:URLに対してのみ観察可能です。解析が行われるときにBlob URL
ストアの検索が関与するためです。
HTMLHyperlinkElementUtilsミックスインを実装する要素には、関連付けられたURLを再初期化するアルゴリズムがあり、次の手順を実行します:
hrefを更新するには、要素のhrefコンテンツ属性の値を、要素のURLにシリアライズされたものに設定します。
href
の getter 手順は次の通りです:
href の setter
手順は、this の href
コンテンツ属性の値を与えられた値に設定することです。
origin の getter 手順は次の通りです:
URL を再初期化します。
オリジンのシリアライズを行い、その結果を返します。this の URL の オリジンを使用します。
protocol の getter 手順は次の通りです:
protocol
の setter 手順は次の通りです:
URL を再初期化します。
与えられた値に ":" を付けて、基本 URL
解析を行います。this の URL を URL として、スキーム開始状態として使用します。
URL パーサーは複数の連続するコロンを無視するため、"https:" や "https::::"
のような値を指定しても、"https" と同じ結果になります。
href を更新します。
username の getter 手順は次の通りです:
username
の setter 手順は次の通りです:
URL を再初期化します。
もし url が null または url が ユーザー名/パスワード/ポートを持てない場合、手順を終了します。
ユーザー名を設定します。url と与えられた値を使用します。
href を更新します。
password の getter 手順は次の通りです:
password
の setter 手順は次の通りです:
URL を再初期化します。
もし url が null または url が ユーザー名/パスワード/ポートを持てない場合、手順を終了します。
パスワードを設定します。url と与えられた値を使用します。
href を更新します。
host
の getter 手順は次の通りです:
host の setter
手順は次の通りです:
URL を再初期化します。
もし url が null または url が 不透明なパスを持つ場合、手順を終了します。
基本 URL 解析 を与えられた値で行い、url と url として、ホスト状態を 状態オーバーライドとして使用します。
href を更新します。
hostname の getter 手順は次の通りです:
hostname
の setter 手順は次の通りです:
URL を再初期化します。
もし url が null または url が 不透明なパスを持つ場合、手順を終了します。
基本 URL 解析 を与えられた値で行い、url と url として、ホスト名の状態を 状態オーバーライドとして使用します。
href を更新します。
port
の getter 手順は次の通りです:
port の setter
手順は次の通りです:
URL を再初期化します。
もし url が null または url が ユーザー名/パスワード/ポートを持てない場合、手順を終了します。
与えられた値が空文字列であれば、url の ポート を null に設定します。
それ以外の場合は、基本 URL 解析 を行い、url を url として、ポート状態を 状態オーバーライドとして使用します。
href を更新します。
pathname の getter 手順は次の通りです:
URL を再初期化します。
もし url が null であれば、空文字列を返します。
url の URL パスをシリアライズ して返します。
pathname
の setter 手順は次の通りです:
search の getter 手順は次の通りです:
search の
setter 手順は次の通りです:
URL を再初期化します。
もし url が null であれば、手順を終了します。
与えられた値が空文字列であれば、url の クエリ を null に設定します。
それ以外の場合:
href を更新します。
hash
の getter 手順は次の通りです:
URL を再初期化します。
もし url が null または url の フラグメント が null または空文字列であれば、空文字列を返します。
url の フラグメント の前に "#" を付けて返します。
hash の setter
手順は次の通りです:
URL を再初期化します。
もし url が null であれば、手順を終了します。
与えられた値が空文字列であれば、url の フラグメント を null に設定します。
それ以外の場合:
href を更新します。
以下のいずれかが該当する場合、要素 element はナビゲートできません:
これは、フォームの送信 にも使用されます。
要素のnoopenerを取得するには、次のステップを実行します:
もし element の リンクタイプ が noopener または noreferrer
キーワードを含む場合、trueを返します。
もし element の リンクタイプ が opener
キーワードを含まない場合、および target が "_blank" に対して ASCII大文字小文字を区別しない 一致である場合、trueを返します。
falseを返します。
次のステップで ハイパーリンクをフォローします:
もし subject が ナビゲートできない場合、処理を終了します。
replace をfalseに設定します。
targetAttributeValue を空文字列に設定します。
もし subject が a
または area
要素である場合、targetAttributeValue を 要素のターゲットを取得した結果に設定します。
noopener を 要素のnoopenerを取得した結果に設定します。
targetNavigable を ナビゲート可能な要素を選ぶルールを適用して得られる最初の値に設定します。
もし targetNavigable が null である場合、処理を終了します。
urlString を URL のエンコード、パース、シリアライズ の結果に設定します。
もし urlString が失敗した場合、処理を終了します。
もし hyperlinkSuffix が null でない場合、urlString に付加します。
referrerPolicy を subject の referrerpolicy コンテンツ属性の現在の状態に設定します。
もし subject の リンクタイプ が noreferrer
キーワードを含む場合、referrerPolicy を "no-referrer" に設定します。
ナビゲート targetNavigable を urlString に subject の ノードドキュメントを使用して行います。
ハイパーリンクのフォローには、完全にロードされていないドキュメントに対して特別な「置換」動作はありません。
すべての現在のエンジンでサポートされています。
場合によっては、リソースはすぐに表示されるのではなく、後で使用されることを意図しています。リソースがすぐに使用されるのではなく、後でダウンロードされることを示すには、download属性をそのリソースへのハイパーリンクを作成するaまたはarea要素に指定できます。
さらに、この属性には値を指定して、ユーザーエージェントがリソースをファイルシステムに保存する際に使用するファイル名を指定することもできます。この値は、`Content-Disposition`
HTTPヘッダーのファイル名パラメータによって上書きされることがあります。[RFC6266]
クロスオリジンの状況では、download属性を`Content-Disposition`
HTTPヘッダー、特にattachmentディスポジションタイプと組み合わせて使用する必要があります。これは、ユーザーが悪意のある活動の可能性を警告されるのを防ぐためです。
(これは、ユーザーが意識せずに個人情報や機密情報をダウンロードさせられるのを防ぐためです。)
ダウンロードするために、要素subjectが作成したハイパーリンクを、オプションのhyperlinkSuffix(デフォルトはnull)およびオプションのuserInvolvement(デフォルトは"none")とともにフォローします。
もしsubjectがナビゲートできない場合、処理を終了します。
もしsubjectのノードドキュメントのアクティブサンドボックスフラグセットがサンドボックス化されたダウンロード閲覧コンテキストフラグを持っている場合、処理を終了します。
urlStringを、subjectのhref属性値を基にURLのエンコード、パース、およびシリアライズした結果に設定します。
もしurlStringが失敗した場合、処理を終了します。
もしhyperlinkSuffixがnullでない場合、urlStringに追加します。
もしuserInvolvementが"ブラウザUI"でない場合:
navigationをsubjectの関連するグローバルオブジェクトのナビゲーションAPIに設定します。
filenameをsubjectのdownload属性の値に設定します。
continueをダウンロードリクエストのnavigateイベントを発火した結果に設定します。destinationURLをurlStringに設定し、userInvolvementをuserInvolvementに設定し、filenameをfilenameに設定します。
もしcontinueがfalseの場合、処理を終了します。
並行して次の手順を実行します:
必要に応じて、ユーザーエージェントはこれらの手順を中止することができます。もしそうすることがユーザーを潜在的な悪意のあるダウンロードから保護すると考えられる場合。
requestをリクエストに新たに設定します。そのURLをurlStringに設定し、クライアントをエントリ設定オブジェクトに設定し、イニシエータを"download"に設定し、宛先を空の文字列に設定し、同期フラグおよびURL認証情報フラグを設定します。
ユーザーエージェントがフェッチされたリソースをダウンロードとして処理する場合、リソースが正常に取得された場合には後で使用するための保存手段をユーザーに提供すべきです。それ以外の場合は、ファイルのダウンロードに関する問題をユーザーに報告すべきです。
ユーザーエージェントがダウンロードとして処理するリソースのファイル名が必要な場合、次のアルゴリズムを使用して選択すべきです。
このアルゴリズムは、信頼できないサイトからのファイルのダウンロードに関わるセキュリティリスクを軽減することを目的としており、ユーザーエージェントはこれに従うことが強く推奨されます。
filenameを未定義の値に設定します。
もしリソースに`Content-Disposition`ヘッダーがあり、そのヘッダーがattachmentディスポジションタイプを指定し、そのヘッダーにファイル名情報が含まれている場合、filenameをそのヘッダーが指定した値に設定し、sanitizeとラベル付けされたステップにジャンプします。[RFC6266]
インターフェースオリジンを、ダウンロードまたはナビゲート操作が開始されたドキュメントのオリジンに設定します。
リソースオリジンを、ダウンロードされているリソースのURLのスキームコンポーネントがdataである場合を除いて、そのURLのオリジンに設定します。この場合、リソースオリジンをインターフェースオリジンと同じに設定します。
もしインターフェースオリジンがない場合、trusted operationをtrueに設定します。そうでない場合、リソースオリジンがインターフェースオリジンと同じオリジンである場合、trusted operationをtrueに、それ以外の場合はfalseに設定します。
もしtrusted operationがtrueであり、リソースに`Content-Disposition`ヘッダーがあり、そのヘッダーにファイル名情報が含まれている場合、filenameをそのヘッダーが指定した値に設定し、sanitizeとラベル付けされたステップにジャンプします。[RFC6266]
もしダウンロードが、aまたはarea要素が作成したハイパーリンクから開始されていない場合、またはダウンロードが開始された時点でその要素にdownload属性がなかった場合、またはその属性が存在していたが、ダウンロードが開始された時点でその値が空文字列であった場合、no
proposed filenameとラベル付けされたステップにジャンプします。
proposed filenameを、ダウンロードが開始された時点でダウンロードを開始したハイパーリンクの要素のdownload属性の値に設定します。
もしtrusted operationがtrueの場合、filenameをproposed filenameの値に設定し、sanitizeとラベル付けされたステップにジャンプします。
もしリソースに`Content-Disposition`ヘッダーがあり、そのヘッダーがattachmentディスポジションタイプを指定している場合、filenameをproposed
filenameの値に設定し、sanitizeとラベル付けされたステップにジャンプします。[RFC6266]
No proposed filename: もしtrusted operationがtrueであるか、またはユーザーがダウンロードを希望している場合、filenameをリソースのURLから派生した値に設定し、sanitizeとラベル付けされたステップにジャンプします。
filenameをユーザーの希望するファイル名またはユーザーエージェントが選択したファイル名に設定し、sanitizeとラベル付けされたステップにジャンプします。
このアルゴリズムがこのステップに到達した場合、異なるオリジンからのリソースがダウンロードされ、かつそのオリジンがファイルをダウンロードするのに適していることを示さず、かつダウンロードがユーザーによって開始されなかったことを意味します。これは、download属性がダウンロードをトリガーするために使用されたか、またはユーザーエージェントがそのリソースをサポートしていないタイプであるためです。
これは危険である可能性があります。例えば、悪意のあるサーバーがユーザーを騙して、プライベート情報を知らずにダウンロードさせ、再度アップロードさせる可能性があります。これを防ぐためには、ユーザーがそのデータがどのソースから来ているかを知る手段が必要であり、潜在的に悪意のあるインターフェースオリジンからの提案されたファイル名は無視されるべきです。
Sanitize: オプションとして、filenameをユーザーが影響を与えることを許可します。例えば、ユーザーエージェントは、ユーザーにファイル名を尋ねる際に、上記で決定されたfilenameの値をデフォルト値として提供することができます。
filenameをローカルファイルシステムに適した形に調整します。
例えば、ファイル名に含まれる無効な文字を削除したり、前後の空白を削除したりすることが含まれます。
もしプラットフォームの慣例がファイルシステム上のファイルタイプを決定するために拡張子を使用しない場合、filenameをファイル名として返します。
claimed typeをリソースのContent-Typeメタデータによって示されたタイプに設定し、named typeをfilenameの拡張子によって示されたタイプに設定します。このステップでは、typeとは、MIMEタイプと拡張子のマッピングを指します。
もしnamed typeがユーザーの好みに一致する場合(例えば、filenameの値がユーザーにプロンプトで尋ねられた場合など)、filenameをファイル名として返します。
もしclaimed typeとnamed typeが同じタイプ(すなわち、リソースのContent-Typeメタデータによって示されたタイプがfilenameの拡張子によって示されたタイプと一致する)である場合、filenameをファイル名として返します。
もしclaimed typeが既知である場合、filenameを調整してclaimed typeに対応する拡張子を追加します。
それ以外の場合、named
typeが潜在的に危険である場合(例えば、プラットフォームの慣例でネイティブ実行可能ファイル、シェルスクリプト、HTMLアプリケーション、または実行可能マクロ対応ドキュメントとして扱われる場合)、filenameを調整して既知の安全な拡張子(例:
".txt")を追加します。
この最後のステップでは、実行可能ファイルのダウンロードが不可能になるため、望ましくない場合があります。セキュリティと使いやすさのバランスを取ることが常に必要です。
filenameをファイル名として返します。
このアルゴリズムの目的のために、ファイル拡張子とは、プラットフォームの慣例がファイルの種類を識別するために使用するファイル名の一部を指します。例えば、多くのオペレーティングシステムでは、ファイル名の最後のドット(".")に続く部分を使用してファイルの種類を決定し、それに基づいてファイルの開き方や実行方法を決定します。
ユーザーエージェントは、リソース自体、URL、および任意のdownload属性によって提供されるディレクトリまたはパス情報を無視し、結果のファイルをユーザーのファイルシステムに保存する場所を決定するべきです。
もし、ハイパーリンクがaまたはarea要素によって作成され、そのハイパーリンクがping属性を持っており、ユーザーがそのハイパーリンクをたどり、その要素のhref属性の値が、要素のノード文書に対して問題なく解析できる場合、ユーザーエージェントはping属性の値を、ASCII空白でその文字列を分割し、結果として得られる各トークンを要素のノード文書に対して解析し、その後、解析に失敗した場合を無視して、各結果URLのping
URLについて、次の手順を実行しなければなりません:
ping URLのスキームがHTTP(S)スキームでない場合、終了します。
任意で、終了します。(例えば、ユーザーエージェントはユーザーの表明された好みに従って、任意のping URLを無視することができます。)
settingsObjectを要素のノード文書の関連する設定オブジェクトとします。
requestを新しいリクエストとし、そのURLをping URLとし、メソッドを`POST`とし、ヘッダーリストを« (`Content-Type`, `text/ping`) »とし、ボディを`PING`とし、クライアントをsettingsObjectとし、宛先を空文字列とし、クレデンシャルモードを"include"とし、リファラーを"no-referrer"とし、URLクレデンシャルフラグを設定し、イニシエータータイプを"ping"とします。
target URLを要素のhref属性の値を基に要素のノード文書に対してURLをエンコード、パース、シリアライズする結果とし、次に:
リクエストをフェッチします。
これは、主なフェッチと並行して行われることがあり、そのフェッチの結果とは無関係です。
ユーザーエージェントは、例えばHTTP `Referer`(参照)ヘッダーの送信を無効にする設定と組み合わせて、この動作を調整できるようにすべきです。ユーザーの好みに基づき、UAsは無視するか、リスト内の特定のURLを無視することができます(例:
サードパーティURLを無視するなど)。これは、上記の手順で明示的に考慮されています。
ユーザーエージェントは、レスポンスに含まれるエンティティボディを無視しなければなりません。ユーザーエージェントは、レスポンスボディの受信を開始した後、接続を早期に閉じることができます。
ping属性が存在する場合、ユーザーエージェントは、ハイパーリンクをたどることで背景で二次的なリクエストが送信されることをユーザーに明確に示すべきです。場合によっては、実際のターゲットURLをリスト表示することも考えられます。
例えば、ビジュアルユーザーエージェントは、ステータスバーやツールチップに、ハイパーリンクの実際のURLとともにターゲットping URLのホスト名を表示することができます。
ping属性は、最も人気のあるオフサイトリンクを追跡したり、広告主がクリック率を追跡したりするためにウェブページが使用する、HTTPリダイレクトやJavaScriptのような既存の技術と冗長です。
しかし、ping属性は、これらの代替手段に対して次の利点をユーザーに提供します:
したがって、この機能がなくてもユーザーを追跡することは可能ですが、著者は、ユーザーエージェントがユーザー体験をより透明にするためにping属性を使用することを推奨します。
Ping-From`ヘッダーと`Ping-To`ヘッダー`Ping-From`ヘッダーと`Ping-To`HTTPリクエストヘッダーは、ハイパーリンク監査リクエストに含まれます。これらの値は、URLであり、シリアライズされたものです。
すべての最新エンジンでサポートされています。
以下の表は、この仕様で定義されたリンクタイプを、それぞれのキーワードに基づいてまとめたものです。この表は規範的ではなく、リンクタイプの実際の定義は次のいくつかのセクションで示されています。
このセクションでは、参照された文書という用語は、リンクを表す要素によって識別されるリソースを指し、現在の文書という用語は、そのリンクを表す要素が見つかるリソースを指します。
link、a、area、またはform要素に適用されるリンクタイプを判断するには、その要素のrel属性をASCII空白で分割する必要があります。結果として得られるトークンは、その要素に適用されるリンクタイプのキーワードです。
特に指定がない限り、キーワードは各rel属性につき一度だけ指定する必要があります。
以下の表の後のいくつかのセクションでは、特定のキーワードの同義語が記載されています。指定された同義語は、ユーザーエージェントによって指定されたとおりに処理される必要がありますが、文書内で使用してはなりません(例えば、キーワード"copyright")。
キーワードは常にASCII大文字小文字を区別しません。比較もそのように行わなければなりません。
したがって、rel="next"はrel="NEXT"と同じです。
body-okなキーワードは、link要素がボディに許可されているかどうかに影響します。body-okなキーワードは、dns-prefetch、modulepreload、pingback、preconnect、prefetch、preload、およびstylesheetです。
ウェブブラウザによって実装される新しいリンクタイプは、この標準に追加されるべきです。残りの部分は拡張として登録できます。
| リンクタイプ | 影響... | body-ok | `Link`処理
| 簡単な説明 | ||
|---|---|---|---|---|---|---|
link
| aおよびarea
| form
| ||||
alternate
| ハイパーリンク | 許可されていません | · | · | 現在の文書の代替表現を提供します。 | |
canonical
| ハイパーリンク | 許可されていません | · | · | 現在の文書の推奨URLを提供します。 | |
author
| ハイパーリンク | 許可されていません | · | · | 現在の文書または記事の著者へのリンクを提供します。 | |
bookmark
| 許可されていません | ハイパーリンク | 許可されていません | · | · | 最も近い先祖セクションのパーマリンクを提供します。 |
dns-prefetch
| 外部リソース | 許可されていません | Yes | · | ユーザーエージェントがターゲットリソースのオリジンのDNS解決を事前に実行することを指定します。 | |
expect
| 内部リソース | 許可されていません | · | · | ターゲットIDを持つ要素が現在の文書内に表示されることを期待します。 | |
external
| 許可されていません | 注釈 | · | · | 参照された文書が現在の文書と同じサイトの一部ではないことを示します。 | |
help
| ハイパーリンク | · | · | コンテキストに基づいたヘルプへのリンクを提供します。 | ||
icon
| 外部リソース | 許可されていません | · | · | 現在の文書を表すアイコンをインポートします。 | |
manifest
| 外部リソース | 許可されていません | · | · | アプリケーションマニフェストをインポートまたはリンクします。アプリケーションマニフェストを参照[MANIFEST] | |
modulepreload
| 外部リソース | 許可されていません | Yes | · | ユーザーエージェントが事前にモジュールスクリプトをフェッチし、文書のモジュールマップに保存して後で評価することを指定します。オプションで、モジュールの依存関係もフェッチできます。 | |
license
| ハイパーリンク | · | · | 現在の文書の主要な内容が、参照された文書によって説明されている著作権ライセンスの対象であることを示します。 | ||
next
| ハイパーリンク | · | · | 現在の文書がシリーズの一部であり、次の文書が参照された文書であることを示します。 | ||
nofollow
| 許可されていません | 注釈 | · | · | 現在の文書の元の著者または発行者が、参照された文書を支持していないことを示します。 | |
noopener
| 許可されていません | 注釈 | · | · | ハイパーリンクが補助的(つまり、適切なtarget属性値を持つ)である場合、それ以外の場合に非補助的ブラウジングコンテキストを持つトップレベルトラバーサブルを作成します。
| |
noreferrer
| 許可されていません | 注釈 | · | · | `Referer`ヘッダーが含まれません。さらに、noopenerと同じ効果があります。
| |
opener
| 許可されていません | 注釈 | · | · | ハイパーリンクがそれ以外の場合に非補助的ブラウジングコンテキストを持つトップレベルトラバーサブルを作成します(つまり、"_blank"としてtarget属性値を持つ)。
| |
pingback
| 外部リソース | 許可されていません | Yes | · | 現在の文書へのピンバックを処理するピンバックサーバーのアドレスを提供します。 | |
preconnect
| 外部リソース | 許可されていません | Yes | Yes | ユーザーエージェントがターゲットリソースのオリジンに事前に接続することを指定します。 | |
prefetch
| 外部リソース | 許可されていません | Yes | · | ユーザーエージェントがターゲットリソースを事前にフェッチし、フォローアップナビゲーションで必要になる可能性が高い場合にキャッシュすることを指定します。 | |
preload
| 外部リソース | 許可されていません | Yes | Yes | ユーザーエージェントがターゲットリソースを事前にフェッチし、現在のナビゲーションのためにキャッシュすることを指定します。この処理は、潜在的な宛先と、優先順位に基づいて行われます。 | |
prev
| ハイパーリンク | · | · | 現在の文書がシリーズの一部であり、前の文書が参照された文書であることを示します。 | ||
privacy-policy
| ハイパーリンク | 許可されていません | · | · | 現在の文書に適用されるデータ収集および使用慣行に関する情報へのリンクを提供します。 | |
search
| ハイパーリンク | · | · | 現在の文書および関連ページを検索するために使用できるリソースへのリンクを提供します。 | ||
stylesheet
| 外部リソース | 許可されていません | Yes | · | スタイルシートをインポートします。 | |
tag
| 許可されていません | ハイパーリンク | 許可されていません | · | · | 現在の文書に適用されるタグ(指定されたアドレスによって識別される)を提供します。 |
terms-of-service
| ハイパーリンク | 許可されていません | · | · | 現在の文書の提供者と、現在の文書を使用したいユーザーとの間の契約に関する情報へのリンクを提供します。 | |
alternate"1つのエンジンでのみサポートされています。
alternateキーワードは、link、a、およびarea要素で使用できます。
このキーワードの意味は、他の属性の値によって異なります。
link要素であり、rel属性にstylesheetキーワードも含まれている場合
alternateキーワードは、stylesheetキーワードの意味をそのキーワードに記載されている方法で修正します。alternateキーワード自体はリンクを作成しません。
ここでは、いくつかのスタイルシートを提供するlink要素のセットを示します:
<!-- 永続的なスタイルシート -->
< link rel = "stylesheet" href = "default.css" >
<!-- 推奨される代替スタイルシート -->
< link rel = "stylesheet" href = "green.css" title = "Green styles" >
<!-- いくつかの代替スタイルシート -->
< link rel = "alternate stylesheet" href = "contrast.css" title = "High contrast" >
< link rel = "alternate stylesheet" href = "big.css" title = "Big fonts" >
< link rel = "alternate stylesheet" href = "wide.css" title = "Wide screen" >
alternateキーワードがtype属性にapplication/rss+xmlまたはapplication/atom+xmlの値が設定されている場合
このキーワードは、シンジケーションフィード(必ずしも現在のページと同じコンテンツをシンジケートするわけではない)を参照するハイパーリンクを作成します。
フィードの自動検出の目的で、ユーザーエージェントは、alternateキーワードを使用し、type属性にapplication/rss+xmlまたはapplication/atom+xmlの値が設定されている文書内のすべてのlink要素を考慮する必要があります。ユーザーエージェントがデフォルトのシンジケーションフィードの概念を持っている場合、最初の要素(ツリー順)をデフォルトとして使用する必要があります。
次のlink要素は、ブログのシンジケーションフィードを提供します:
< link rel = "alternate" type = "application/atom+xml" href = "posts.xml" title = "Cool Stuff Blog" >
< link rel = "alternate" type = "application/atom+xml" href = "posts.xml?category=robots" title = "Cool Stuff Blog: robots category" >
< link rel = "alternate" type = "application/atom+xml" href = "comments.xml" title = "Cool Stuff Blog: Comments" >
これらのlink要素は、フィード自動検出に従事しているユーザーエージェントによって使用され、最初の要素がデフォルトとして使用されます(該当する場合)。
次の例では、a要素を使用して、さまざまなシンジケーションフィードをユーザーに提供します:
< p > You can access the planets database using Atom feeds:</ p >
< ul >
< li >< a href = "recently-visited-planets.xml" rel = "alternate" type = "application/atom+xml" > Recently Visited Planets</ a ></ li >
< li >< a href = "known-bad-planets.xml" rel = "alternate" type = "application/atom+xml" > Known Bad Planets</ a ></ li >
< li >< a href = "unexplored-planets.xml" rel = "alternate" type = "application/atom+xml" > Unexplored Planets</ a ></ li >
</ ul >
これらのリンクは、フィード自動検出では使用されません。
このキーワードは、現在の文書の代替表現を参照するハイパーリンクを作成します。
参照された文書の性質は、hreflangおよびtype属性によって示されます。
alternateキーワードがhreflang属性と共に使用され、その属性の値が文書要素の言語と異なる場合、それは参照された文書が翻訳であることを示します。
alternateキーワードがtype属性と共に使用される場合、それは参照された文書が指定された形式での現在の文書の再構成であることを示します。
hreflangおよびtype属性は、alternateキーワードと共に指定される場合、組み合わせて使用できます。
次の例では、他の言語を対象とし、他のメディアを対象とする代替フォーマットを使用したページのバージョンを指定する方法を示します:
< link rel = alternate href = "/en/html" hreflang = en type = text/html title = "English HTML" >
< link rel = alternate href = "/fr/html" hreflang = fr type = text/html title = "French HTML" >
< link rel = alternate href = "/en/html/print" hreflang = en type = text/html media = print title = "English HTML (for printing)" >
< link rel = alternate href = "/fr/html/print" hreflang = fr type = text/html media = print title = "French HTML (for printing)" >
< link rel = alternate href = "/en/pdf" hreflang = en type = application/pdf title = "English PDF" >
< link rel = alternate href = "/fr/pdf" hreflang = fr type = application/pdf title = "French PDF" >
この関係は推移的です。つまり、1つの文書がリンクタイプ"alternate"で他の2つの文書にリンクしている場合、それはその2つの文書が最初の文書の代替表現であることを意味するだけでなく、それらの2つの文書が互いに代替表現であることも意味します。
author"authorキーワードは、link、a、およびarea要素で使用できます。このキーワードはハイパーリンクを作成します。
aおよびarea要素の場合、authorキーワードは、参照された文書がハイパーリンクを定義している要素の最も近い先祖であるarticle要素の著者についての追加情報を提供することを示します。もしそのような要素が存在しない場合は、ページ全体の著者についての追加情報を提供します。
link要素の場合、authorキーワードは、参照された文書がページ全体の著者についての追加情報を提供することを示します。
"参照された文書"は、mailto:URLであり、著者のメールアドレスを示すことができますし、実際にそうであることが多いです。[MAILTO]
同義語: 歴史的な理由から、ユーザーエージェントはlink、a、およびarea要素にrev属性の値が"made"であるものを、リンク関係としてauthorキーワードが指定されているものとして扱わなければなりません。
bookmark"bookmarkキーワードは、aおよびarea要素で使用できます。このキーワードはハイパーリンクを作成します。
bookmarkキーワードは、リンクしている要素の最も近い先祖であるarticle要素、または該当するarticle要素がない場合は、リンク要素が最も密接に関連しているセクションのパーマリンクを提供します。
次のスニペットには、3つのパーマリンクがあります。ユーザーエージェントは、パーマリンクが与えられている場所を見て、どのパーマリンクが仕様のどの部分に適用されるかを判断できます。
...
< body >
< h1 > パーマリンクの例</ h1 >
< div id = "a" >
< h2 > 最初の例</ h2 >
< p >< a href = "a.html" rel = "bookmark" > このパーマリンクは、最初のH2から2番目のH2までのコンテンツにのみ適用されます</ a > 。DIVは正確にはそのセクションではありませんが、それに大まかに対応しています。</ p >
</ div >
< h2 > 2番目の例</ h2 >
< article id = "b" >
< p >< a href = "b.html" rel = "bookmark" > このパーマリンクは、外側のARTICLE要素に適用されます</ a > (例えば、ブログ記事のように)。</ p >
< article id = "c" >
< p >< a href = "c.html" rel = "bookmark" > このパーマリンクは、内側のARTICLE要素に適用されます</ a > (例えば、ブログのコメントのように)。</ p >
</ article >
</ article >
</ body >
...
canonical"canonical キーワードは link 要素と共に使用できます。このキーワードは ハイパーリンク を作成します。
canonical キーワードは、href
属性で指定されたURLが現在のドキュメントにとって推奨されるURLであることを示します。これにより、検索エンジンが重複コンテンツを減らすのに役立ちます。詳細はThe Canonical Link
Relation に記載されています。[RFC6596]
dns-prefetch"dns-prefetch
キーワードは link
要素と共に使用できます。このキーワードは 外部リソースリンク を作成します。このキーワードは body-ok です。
dns-prefetch
キーワードは、指定されたリソースの オリジン
のDNS解決を事前に行うことが有益である可能性が高いことを示します。これは、ユーザーがそのオリジンにあるリソースを必要とする可能性が非常に高いためであり、DNS解決に関連する遅延コストを事前に解決することでユーザーエクスペリエンスが向上します。
dns-prefetch
キーワードによって指定されたリソースのデフォルトタイプはありません。
この種類のリンクをフェッチして処理する 適切なタイミングは次のとおりです:
外部リソースリンク が、すでに ブラウジングコンテキストに接続されている link 要素に作成されたとき。
外部リソースリンク の link 要素が ブラウジングコンテキストに接続されたとき。
すでに ブラウジングコンテキストに接続されている 外部リソースリンクの link 要素の href 属性が変更されたとき。
この種類のリンクリソースをフェッチして処理する 手順は、次のとおりです:
el の href
属性の値を el の ノードドキュメント
に対して相対的に指定して、URLのエンコードと解析 を行った結果として url を取得します。
url が失敗した場合、返します。
partitionKey を、ネットワークパーティションキーを決定する 結果として取得します。
ユーザーエージェントは、partitionKey と url の オリジン を指定して オリジンを解決 する必要があります。
このアルゴリズムの結果はキャッシュできるため、将来のフェッチが高速化される可能性があります。
expect"
expect キーワードは link 要素と共に使用できます。このキーワードは 内部リソースリンク を作成します。
内部リソースリンク は、expect
キーワードによって作成され、リンクされている要素がドキュメントに接続され、完全に解析されるまでレンダリングを ブロック するために使用されます。
expect
キーワードによって指定されたリソースのデフォルトタイプはありません。
次のいずれかの条件が link 要素
el に対して発生する場合:
expect 内部リソースリンク が、すでに ブラウジングコンテキストに接続されている el に作成された場合。
expect 内部リソースリンク が
el に作成され、el が ブラウジングコンテキストに接続された 場合。
expect内部リソースリンク が
el に作成され、el がすでに ブラウジングコンテキストに接続されている 場合、および el の
href 属性が設定、変更、または削除された場合。
expect 内部リソースリンク が
el に作成され、el がすでに ブラウジングコンテキストに接続されている 場合、および el の
media 属性が設定、変更、または削除された場合、
そのときは、処理 el を実行します。
リンク 要素 el に対して、内部リソースリンクを処理するには、次の手順を実行します:
el の ノードドキュメント を doc とします。
el の href
属性の値を指定して URLのエンコードと解析
を行った結果として url を取得します。
doc および url に対して 示された部分を選択する 結果として indicatedElement を取得します。
次のすべてが真である場合:
doc の 現在のドキュメントの準備状態 が "loading"
である。
el が 内部リソースリンク を作成している。
el が ブラウジングコンテキストに接続されている。
el が 潜在的にレンダリングをブロックする可能性がある。
indicatedElement が要素ではないか、または 開いている要素のスタック 上にあり、その関連する HTML パーサー が doc に関連付けられている。
その場合、レンダリングをブロック します el で。
それ以外の場合、レンダリングを解除 します el で。
Document doc に対して、内部リソースリンクを処理するには:
各 expect リンク 要素 link を
doc の レンダリングブロック要素セット 内で 処理
します。
属性変更手順
は、element、localName、value、および namespace を指定して、expect リンク 要素が動的に id および name の変更に対応することを保証するために使用されます:
namespace が null でない場合、終了します。
element が 開いている要素のスタック 上にある場合、終了します。
次のいずれかが真である場合:
その場合、内部リソースリンクを処理する を element の ノードドキュメント に対して実行します。
external"external キーワードは、a、area、および form 要素と共に使用できます。このキーワードは ハイパーリンク
を作成しませんが、要素によって作成された他のハイパーリンク(他のキーワードが作成しない場合は暗示されたハイパーリンク)に 注釈 を付けます。
external
キーワードは、リンクが現在のドキュメントが構成するサイトの一部ではないドキュメントに導いていることを示します。
help"help キーワードは、link、a、area、および form 要素と共に使用できます。このキーワードは ハイパーリンク を作成します。
a、area、および form 要素に対して、help
キーワードは、ハイパーリンクを定義する要素の親要素とその子要素のために、参照されるドキュメントがさらに支援情報を提供することを示します。
次の例では、フォームコントロールに関連するコンテキストに応じたヘルプが関連付けられています。ユーザーエージェントは、この情報を使用して、たとえば、ユーザーが「ヘルプ」または「F1」キーを押した場合に参照されたドキュメントを表示することができます。
< p >< label > Topic: < input name = topic > < a href = "help/topic.html" rel = "help" > (Help)</ a ></ label ></ p >
link 要素に対して、help
キーワードは、参照されるドキュメントがページ全体のヘルプを提供することを示します。
a および area 要素に対して、一部のブラウザでは、help キーワードがリンクに異なるカーソルを使用させることがあります。
icon"現在のすべてのエンジンでサポートされています。
icon キーワードは link 要素と共に使用できます。このキーワードは 外部リソースリンク を作成します。
指定されたリソースはページまたはサイトを表すアイコンであり、ユーザーエージェントがユーザーインターフェイスでページを表す際に使用する必要があります。
アイコンは、聴覚アイコン、視覚アイコン、またはその他の種類のアイコンである可能性があります。複数のアイコンが提供されている場合、ユーザーエージェントは type、media、および sizes
属性に基づいて最も適切なアイコンを選択する必要があります。複数の等しく適切なアイコンがある場合、ユーザーエージェントはアイコンのリストを収集した時点で ツリー順
で最後に宣言されたアイコンを使用しなければなりません。ユーザーエージェントがアイコンを使用しようとしたが、そのアイコンが実際には不適切であると判断された場合(たとえば、サポートされていない形式を使用しているため)、ユーザーエージェントは属性によって判断された次に適切なアイコンを試す必要があります。
ユーザーエージェントはアイコンのリストが変更されたときにアイコンを更新する必要はありませんが、更新することが推奨されます。
icon キーワードによって指定されるリソースにはデフォルトのタイプがありません。ただし、リソースのタイプを判別する ために、ユーザーエージェントはリソースが画像であると想定する必要があります。
sizes キーワードは、ピクセル単位のアイコンサイズを表します(CSSピクセル
ではなく、元のピクセルで表されます)。
2x(192dpi)表示用に意図された幅50 CSSピクセル のアイコンは、100ピクセルの幅を持つ必要があります。この機能は、小さい高解像度アイコンと大きい低解像度アイコンに異なるリソースを使用することを示すことをサポートしていません(たとえば、50×50 2xと100×100 1x)。
属性の値を解析して処理するには、ユーザーエージェントは最初に属性の値を ASCII空白文字で分割 し、次に各結果のキーワードを解析してそれが何を表しているかを決定する必要があります。
any キーワードは、リソースがスケーラブルアイコン(たとえば、SVG画像で提供されるもの)を含んでいることを表します。
その他のキーワードは、それが何を表しているかを判断するために、次のようにさらに解析する必要があります。
キーワードに U+0078 LATIN SMALL LETTER X または U+0058 LATIN CAPITAL LETTER X 文字が1つだけ含まれていない場合、そのキーワードは何も表しません。そのキーワードに戻ります。
幅文字列 は "x" または "X" の前の文字列です。
高さ文字列 は "x" または "X" の後の文字列です。
幅文字列 または 高さ文字列 のいずれかが U+0030 DIGIT ZERO (0) 文字で始まるか、ASCII数字 以外の文字を含んでいる場合、そのキーワードは何も表しません。そのキーワードに戻ります。
負でない整数を解析するルール を 幅文字列 に適用して、幅 を取得します。
負でない整数を解析するルール を 高さ文字列 に適用して、高さ を取得します。
キーワードは、リソースに幅が 幅 デバイスピクセル、高さが 高さ デバイスピクセルのビットマップアイコンが含まれていることを表します。
sizes
属性に指定されたキーワードは、リンクされたリソースで実際に利用可能でないアイコンサイズを表してはいけません。
link 要素 el および リクエスト request に対するこのタイプのリンクリソースのための リンクリソースフェッチ設定ステップ
は次のとおりです。
request の 送信先 を
"image" に設定します。
true を返します。
このタイプのリンクリソースに対する リンクヘッダを処理する ステップは何もしません。
コード icon キーワードを持つ link が存在しない場合、スキーム が HTTP(S)スキーム である Document オブジェクトに対して、ユーザーエージェントはこれらのステップを並行して実行できます。
request を新しい リクエスト として、URL を URLレコード
であり、/favicon.ico を Document
オブジェクトの URL に対して解決されたものとします。クライアント は Document オブジェクトの 関連設定オブジェクト、送信先 は
"image"、同期フラグ
は設定されており、クレデンシャルモード は "include"、URLクレデンシャルフラグを使用 は設定されています。
response を フェッチ request の結果とします。
response の 非安全なレスポンス をアイコンとして使用し、それが
icon キーワードを使用して宣言されたかのように処理します。
次のスニペットは、複数のアイコンを含むアプリケーションの上部を示しています。
<!DOCTYPE HTML>
< html lang = "en" >
< head >
< title > lsForums — Inbox</ title >
< link rel = icon href = favicon.png sizes = "16x16" type = "image/png" >
< link rel = icon href = windows.ico sizes = "32x32 48x48" type = "image/vnd.microsoft.icon" >
< link rel = icon href = mac.icns sizes = "128x128 512x512 8192x8192 32768x32768" >
< link rel = icon href = iphone.png sizes = "57x57" type = "image/png" >
< link rel = icon href = gnome.svg sizes = "any" type = "image/svg+xml" >
< link rel = stylesheet href = lsforums.css >
< script src = lsforums.js ></ script >
< meta name = application-name content = "lsForums" >
</ head >
< body >
...
歴史的な理由から、icon キーワードの前に "shortcut"
キーワードが付くことがあります。"shortcut" キーワードが存在する場合、rel 属性の全体の値は、文字間に U+0020
スペース文字が1つだけ含まれており、他の ASCII空白文字 が含まれていない "shortcut icon" 文字列と ASCII大文字小文字の区別なく一致している必要があります。
license"license キーワードは、link、a、area、およびform要素で使用することができます。このキーワードはハイパーリンクを作成します。
licenseキーワードは、参照されたドキュメントが、現在のドキュメントの主なコンテンツが提供されている著作権ライセンス条件を提供することを示します。
この仕様では、ドキュメントの主なコンテンツと、主なコンテンツとは見なされないコンテンツを区別する方法を指定していません。この区別はユーザーに明確に示すべきです。
写真共有サイトを考えてみましょう。このサイトのページは写真を説明し、表示するものであり、そのページは次のようにマークアップされるかもしれません:
<!DOCTYPE HTML>
< html lang = "en" >
< head >
< title > Exampl Pictures: Kissat</ title >
< link rel = "stylesheet" href = "/style/default" >
</ head >
< body >
< h1 > Kissat</ h1 >
< nav >
< a href = "../" > Return to photo index</ a >
</ nav >
< figure >
< img src = "/pix/39627052_fd8dcd98b5.jpg" >
< figcaption > Kissat</ figcaption >
</ figure >
< p > One of them has six toes!</ p >
< p >< small >< a rel = "license" href = "http://www.opensource.org/licenses/mit-license.php" > MIT Licensed</ a ></ small ></ p >
< footer >
< a href = "/" > Home</ a > | < a href = "../" > Photo index</ a >
< p >< small > © copyright 2009 Exampl Pictures. All Rights Reserved.</ small ></ p >
</ footer >
</ body >
</ html >
この場合、licenseは写真(ドキュメントの主なコンテンツ)のみに適用され、ドキュメント全体には適用されません。特に、ドキュメントのデザインは、ドキュメントの下部に記載された著作権によって保護されており、このことをスタイリングでより明確にすることができます(例えば、ライセンスリンクを写真の近くに目立つように配置し、ページの著作権情報はページの下部に小さく薄く表示する)。
同義語: 歴史的な理由から、ユーザーエージェントは "copyright" キーワードを license キーワードと同様に扱う必要があります。
manifest"サポートは1つのエンジンのみ。
manifest
キーワードは、link要素で使用できます。
このキーワードは外部リソースリンクを作成します。
manifest
キーワードは、現在のドキュメントに関連するメタデータを提供するマニフェストファイルを示します。
manifestキーワードで指定されたリソースには、デフォルトのタイプはありません。
ウェブアプリケーションがインストールされていない場合、このリンクタイプのリンクされたリソースをフェッチおよび処理する適切なタイミングは、ユーザーエージェントが必要と判断したときです。例えば、ユーザーがウェブアプリケーションをインストールすることを選択したときです。
インストールされたウェブアプリケーションの場合、このリンクタイプのリンクされたリソースをフェッチおよび処理する適切なタイミングは次の通りです。
外部リソースリンクが、すでにブラウジングコンテキストに接続されている link要素に作成されたとき。
すでにブラウジングコンテキストに接続されている link要素の href 属性が変更されたとき。
いずれの場合でも、ツリー順序で link 属性が最初に rel 属性に含まれる manifest
トークンを使用できる要素のみが使用されます。
ユーザーエージェントは、このリンクタイプに対してロードイベントを遅延させてはなりません。
このリンクタイプのリンクされたリソースに対するリンクされたリソースのフェッチ設定手順は、 link要素 elとリクエスト request に与えられたときの手順です。
navigable がnullの場合、falseを返します。
navigable が トップレベルのトラバーサブル でない場合、falseを返します。
request のイニシエーター を "manifest" に設定します。
request の宛先
を "manifest" に設定します。
request のモード を
"cors" に設定します。
request の資格情報モード を el の crossorigin
コンテンツ属性のCORS設定属性資格情報モードに設定します。
trueを返します。
リンクされたリソースを処理するには、link 要素 el、ブール値
success、レスポンス response、およびバイトシーケンス bodyBytes を与えます。
response の コンテンツタイプメタデータ がJSON MIMEタイプでない場合、success をfalseに設定します。
success がtrueの場合:
マニフェストURL を response の URL に設定します。
マニフェストを処理し、 ドキュメントURL、 マニフェストURL および bodyBytes を指定します。[MANIFEST]
リンクヘッダーを処理する手順は、何もしないようにします。
modulepreload"modulepreload
キーワードは、link
要素で使用できます。このキーワードは、外部リソースリンク
を作成します。このキーワードはbody-okです。
modulepreload
キーワードは、preload
キーワードの特化した代替手段であり、モジュールスクリプト
を事前にロードするための処理モデルに焦点を当てています。特に、モジュールスクリプトの特定のフェッチ動作(例:crossorigin
属性の異なる解釈を含む)を使用し、結果を後で評価するための適切な
モジュールマップ
に配置します。対照的に、preload
キーワードを使用した同様の外部リソースリンク
は、ドキュメントのモジュールマップに影響を与えずに、結果をプリロードキャッシュに配置します。
さらに、実装はモジュールスクリプト
が依存関係を宣言することを利用して、指定されたモジュールの依存関係もフェッチすることができます。これは最適化の機会として意図されており、ユーザーエージェントはその依存関係が後で必要になる可能性が高いことを知っているためです。技術的な手段がない限り、一般的には観測されません。特に、適切な
load または
error
イベントは、指定されたモジュールがフェッチされた後に発生し、依存関係を待つことはありません。
ユーザーエージェントは、このリンクタイプのためにロードイベントを遅延させてはなりません。
リンクされたリソースをフェッチして処理する適切なタイミングは、次の通りです:
外部リソースリンクが既にブラウジングコンテキストに接続されているリンク要素上に作成されたとき。
他のリンク関係とは異なり、as、crossorigin、referrerpolicyなどの関連属性を変更しても、新しいフェッチはトリガーされません。これは、ドキュメントのモジュールマップが既存のフェッチで既にポピュレートされているためであり、再フェッチは無意味だからです。
リンクされたリソースをフェッチして処理するためのアルゴリズムは、modulepreloadリンクがリンク要素elである場合に適用され、次の手順で実行されます:
もしelのhref属性の値が空文字列である場合は、終了します。
elのas属性(destination)の現在の状態をdestinationとし、状態がない場合は「script」とします。
もしdestinationがscript-likeでない場合、要素タスクをキューに追加し、ネットワーキングタスクソースにelを渡して、イベントを発火させます。このイベントはerrorという名前で、elに対して発火されます。その後、処理を終了します。
elのhref属性の値をもとにurlをエンコーディングパースして決定し、elのノードドキュメントに相対するURLを取得します。
もしurlがエラーとなった場合は、終了します。
elのノードドキュメントの関連設定オブジェクトをsettings objectとします。
elのcrossorigin属性に対応するCORS設定属性のクレデンシャルモードをcredentials
modeとします。
elの[[CryptographicNonce]]をcryptographic nonceとします。
もしelがintegrity属性を持たない場合は、integrity
metadataを、urlとsettings objectを使ってモジュールインテグリティメタデータを解決する結果に設定します。
elのreferrerpolicy属性の現在の状態をreferrer
policyとします。
elのfetchpriority属性の現在の状態をfetch
priorityとします。
モジュールプリロードモジュールスクリプトグラフをフェッチするために、url、destination、settings object、optionsを使用して、次のステップを実行します:
リンクヘッダーを処理するこのタイプのリンクリソースのステップは、何も行いません。
次のスニペットは、複数のモジュールをプリロードしたアプリケーションの上部を示しています:
<!DOCTYPE html>
< html lang = "en" >
< title > IRCFog</ title >
< link rel = "modulepreload" href = "app.mjs" >
< link rel = "modulepreload" href = "helpers.mjs" >
< link rel = "modulepreload" href = "irc.mjs" > < link rel = "modulepreload" href = "fog-machine.mjs" >
< script type = "module" src = "app.mjs" >
...
このアプリケーションのモジュールグラフは次のように仮定します:
ここで、アプリケーション開発者は、modulepreload
を使用して、モジュールグラフ内のすべてのモジュールを宣言し、ユーザーエージェントがそれらすべてのフェッチを開始するようにしています。このようなプリロードがない場合、HTTP/2 Server
Pushなどの技術が導入されていない場合、ユーザーエージェントはhelpers.mjsを発見するまでに複数のネットワークリクエストを行う必要があるかもしれません。このようにして、modulepreload
link
要素をアプリケーションのモジュールの「マニフェスト」として使用することができます。
次のコードは、modulepreload
リンクがimport()
と組み合わせて使用され、ネットワークフェッチが事前に行われることを保証し、import()
が呼び出されたときにモジュールがすでに準備され(ただし評価はされていない)、モジュールマップに配置されていることを示しています:
< link rel = "modulepreload" href = "awesome-viewer.mjs" >
< button onclick = "import('./awesome-viewer.mjs').then(m => m.view())" >
素晴らしいものを見る
</ button >
nofollow」nofollowキーワードは、
a、
area、
およびform要素で使用できます。この
キーワードはハイパーリンクを作成しませんが、要素によって
作成された他のハイパーリンク(他のキーワードが作成しない場合は暗黙のハイパーリンク)を注釈します。
nofollow
キーワードは、リンクがページの元の著者または発行者によって承認されていないこと、またはリンク先の文書へのリンクが、
主に二つのページに関係する人物間の商業関係のために含まれていることを示します。
noopener」現在のすべてのエンジンでサポートされています。
noopener
キーワードは、a、
area、
およびform要素で使用できます。この
キーワードはハイパーリンクを作成しませんが、要素によって
作成された他のハイパーリンク(他のキーワードが作成しない場合は暗黙のハイパーリンク)を注釈します。
このキーワードは、新しく作成されたトップレベルのトラバーサブルが
ハイパーリンクを辿ることで作成された場合、
補助ブラウジングコンテキストを含まないことを示します。
例えば、結果として得られるWindowの
openerゲッターはnullを返します。
また、処理モデルも参照してください。
これは通常、トップレベルのトラバーサブルと
補助ブラウジングコンテキストを作成します
(既存のナビゲーブルがなく、その
ターゲット名が「example」ではないと仮定します):
< a href = help.html target = example > Help!</ a >
これは同じ条件下で、補助ブラウジングコンテキストを含まないトップレベルのトラバーサブルを作成します:
< a href = help.html target = example rel = noopener > Help!</ a >
これらは同等であり、親ナビゲーブルのみをナビゲートします:
< a href = index.html target = _parent > Home</ a >
< a href = index.html target = _parent rel = noopener > Home</ a >
noreferrer」
すべての現在のエンジンでサポートされています。
noreferrer
キーワードは、a、
area、
およびform要素で使用できます。この
キーワードはハイパーリンクを作成しませんが、要素によって
作成された他のハイパーリンク(他のキーワードが作成しない場合は暗黙のハイパーリンク)を注釈します。
これは、リンクを辿る際にリファラー情報が漏れないことを示し、同じ条件下でnoopenerキーワードの動作をも暗示します。
リファラーが直接操作される処理モデルも参照してください。
<a href="..." rel="noreferrer" target="_blank">は<a href="..." rel="noreferrer noopener" target="_blank">と同じ動作をします。
opener」openerキーワードは、a、
area、
およびform要素で使用できます。このキーワードはハイパーリンクを作成しませんが、要素によって作成された他のハイパーリンク(他のキーワードが作成しない場合は暗黙のハイパーリンク)を注釈します。
このキーワードは、ハイパーリンクに従った結果、新たに作成されたトップレベルのトラバーサブルに補助的なブラウジングコンテキストが含まれることを示します。
また、処理モデルも参照してください。
次の例では、openerを使用して、ヘルプページのポップアップがオープナーをナビゲートできるようにしています。例えば、ユーザーが探している情報が別の場所にある場合などです。代替案としては、_blankの代わりに名前付きターゲットを使用することも考えられますが、既存の名前と競合する可能性があります。
< a href = "..." rel = opener target = _blank > Help!</ a >
pingback」pingbackキーワードは、link要素で使用できます。このキーワードは外部リソースリンクを作成します。このキーワードはbody-okです。
pingbackキーワードの意味については、Pingback
1.0を参照してください。[PINGBACK]
preconnect」
すべての現行エンジンでサポートされています。
preconnectキーワードは、link要素で使用できます。このキーワードは外部リソースリンクを作成します。このキーワードはbody-okです。
preconnectキーワードは、指定されたリソースのオリジンへの接続を予め開始することが有益である可能性が高いことを示します。つまり、そのオリジンに存在するリソースをユーザーが必要とする可能性が高く、接続確立に伴う遅延コストを事前に処理することでユーザーエクスペリエンスが向上します。
preconnectキーワードによって指定されたリソースにはデフォルトのタイプはありません。
このリンクタイプでは、ロードイベントを遅延させてはいけません。
このタイプのリンクをフェッチして処理する適切なタイミングは以下の通りです。
外部リソースリンクが、既にブラウジングコンテキストに接続されている link要素で作成された場合。
既にブラウジングコンテキストに接続されている link要素のcrossorigin属性が設定、変更、または削除された場合。
リンクリソースのフェッチと処理手順は、link要素elが与えられた場合に、リンクオプションを作成し、その結果に基づいて事前接続を実行します。
このタイプのリンクリソースに対してリンクヘッダを処理する手順は、リンク処理オプション optionsが与えられた場合に、事前接続を実行することです。
事前接続をリンク処理オプション optionsに対して実行する方法:
optionsのhrefが空文字列である場合、処理を終了します。
optionsのhrefをURLのエンコード解析を行い、optionsのベースURLに相対的に解釈されたurlを取得します。
ベースURLを文書や環境の代わりに渡すことについては、issue #9715で追跡されています。
urlが失敗した場合、処理を終了します。
urlのスキームがHTTP(S)スキームでない場合、処理を終了します。
partitionKeyをネットワークパーティションキーの決定の結果として取得します。
useCredentialsをtrueに設定します。
もしoptionsのcrossoriginがAnonymousであり、optionsのoriginがurlのオリジンと同一オリジンでない場合、useCredentialsをfalseに設定します。
ユーザーエージェントは、partitionKey、urlのオリジン、およびuseCredentialsを指定して接続を取得する必要があります。
この接続は取得されますが、直接使用されることはありません。それは後続の使用のために接続プールに残ります。
ユーザーエージェントは可能な限り事前接続を開始し、完全な接続ハンドシェイク(HTTPの場合はDNS+TCP、HTTPSのオリジンの場合はDNS+TCP+TLS)を実行するべきですが、リソースの制約や他の理由で部分的なハンドシェイク(HTTPの場合はDNSのみ、HTTPSの場合はDNSまたはDNS+TCP)を実行するか、完全にスキップすることを選択することが許されています。
オリジンごとの最適な接続数は、交渉されたプロトコル、ユーザーの現在の接続プロファイル、利用可能なデバイスリソース、グローバル接続制限、および他のコンテキスト固有の変数に依存します。その結果、開かれる接続数の決定はユーザーエージェントに委ねられています。
prefetch」prefetchキーワードは、link要素で使用できます。このキーワードは外部リソースリンクを作成します。このキーワードはbody-okです。
prefetchキーワードは、指定されたリソースまたは同一サイトのドキュメントを事前にフェッチしてキャッシュすることが有益である可能性が高いことを示します。これは、ユーザーが将来のナビゲーションでこのリソースを必要とする可能性が高いためです。
prefetchキーワードによって指定されたリソースにはデフォルトのタイプはありません。
このタイプのリンクをフェッチして処理する適切なタイミングは以下の通りです。
外部リソースリンクが、既にブラウジングコンテキストに接続されている link要素で作成された場合。
既にブラウジングコンテキストに接続されている link要素のcrossorigin属性が設定、変更、または削除された場合。
リンクリソースのフェッチと処理アルゴリズムは、prefetchリンクが与えられた場合に、link要素elに対して次のように行われます。
elのhref属性の値が空文字列の場合、処理を終了します。
optionsをelからリンクオプションを作成する結果として取得します。
optionsの宛先を空文字列に設定します。
requestをoptionsからリンクリクエストを作成する結果として取得します。
requestがnullである場合、処理を終了します。
requestのイニシエーターを「prefetch」に設定します。
processPrefetchResponseを、レスポンス responseとnull、失敗、またはバイトシーケンス bytesOrNullに対して次の手順を行うものとして設定します。
ユーザーエージェントは、requestをフェッチし、processResponseConsumeBodyをprocessPrefetchResponseに設定します。ユーザーエージェントは、現在のドキュメントに必要な他のリクエストを優先するために、requestのフェッチを遅延させることができます。
リンクヘッダを処理する手順は、何もしないことです。
preload"1つのエンジンのみ対応しています。
preloadキーワードは、link要素で使用できます。このキーワードは、外部リソースリンクを作成します。このキーワードはbody-okです。
preloadキーワードは、ユーザーエージェントが指定されたリソースをあらかじめフェッチしてキャッシュすることを示します。これは、as属性によって指定された潜在的な宛先と、fetchpriority属性によって指定された優先度に従って行われます。このリソースが現在のナビゲーションに必要である可能性が高いためです。
ユーザーエージェントは、リソースがロードされた際に追加の操作を行う場合があります。例えば、画像をデコードしたり、スタイルシートを作成したりすることです。しかし、これらの追加操作は観察可能な効果を持つことはできません。
preloadキーワードに指定されるリソースのデフォルトタイプはありません。
ユーザーエージェントは、このリンクタイプに対してロードイベントを遅延させることはできません。
このリンクに対してリンクされたリソースをフェッチして処理する適切なタイミングは次のとおりです:
外部リソースリンクが、すでにブラウジングコンテキストに接続されている要素上に作成されたとき。
すでにブラウジングコンテキストに接続されている外部リソースリンクのlink要素のhref属性が変更されたとき。
すでにブラウジングコンテキストに接続されている外部リソースリンクのlink要素のas属性が変更されたとき。
すでにブラウジングコンテキストに接続されている外部リソースリンクのlink要素のtype属性が、リクエストの宛先に対してサポートされていないタイプを指定していたために以前は取得されなかったが、それが設定、削除、または変更されたとき。
すでにブラウジングコンテキストに接続されている外部リソースリンクのlink要素のmedia属性が、以前は環境と一致しなかったために取得されなかったが、それが変更または削除されたとき。
ドキュメントにはプリロードされたリソースのマップがあります。これは順序付けられたマップで、初期状態では空です。
プリロードされたリソースを消費するために、ウィンドウ windowが、URL
url、文字列 destination、文字列 mode、文字列 credentialsMode、文字列
integrityMetadata、およびレスポンスを受け入れるアルゴリズム
onResponseAvailableを指定した場合:
keyをプリロードキーとし、そのURLがurl、宛先がdestination、モードがmode、および資格情報モードがcredentialsModeであるものとします。
preloadsをwindowの関連ドキュメントのプリロードされたリソースのマップとします。
もしkeyがpreloads内に存在しない場合は、falseを返します。
entryをpreloads[key]とします。
consumerIntegrityMetadataを、integrityMetadataの解析結果とします。
次の条件のいずれにも当てはまらない場合:
consumerIntegrityMetadataがメタデータなしである場合;
consumerIntegrityMetadataがpreloadIntegrityMetadataと等しい場合;
この比較では未知の整合性オプションを無視します。issue #116を参照してください。
その場合はfalseを返します。
プリロードと消費者間で整合性メタデータが一致しない場合、データが一致していても、ネットワークから追加のフェッチが行われます。
プリロードキャッシュにネットワークエラーが追加されることが重要です。これにより、プリロードリクエストがエラーになった場合、エラーレスポンスが後でネットワークから再リクエストされることがなくなります。これにはセキュリティ上の影響もあります。たとえば、開発者がプリロードリクエストにサブリソース整合性メタデータを指定したが、続くリソースリクエストには指定しなかった場合、プリロードリクエストがサブリソース整合性検証に失敗し、破棄されたとしても、そのリソースリクエストはネットワークから整合性が検証されていない潜在的に悪意のあるレスポンスをフェッチして消費する可能性があります。[SRI]
削除する preloads[key]
もしentryのレスポンスがNullである場合、entryのレスポンスが利用可能なときをonResponseAvailableに設定します。
それ以外の場合は、entryのレスポンスを使用してonResponseAvailableを呼び出します。
trueを返します。
このセクションの目的のために、文字列typeが文字列destinationと一致するのは、次のアルゴリズムがtrueを返す場合です:
もしtypeが空文字列である場合はtrueを返します。
もしdestinationが"fetch"である場合はtrueを返します。
mimeTypeRecordをパースした結果とします。
もしmimeTypeRecordが失敗した場合はfalseを返します。
もしmimeTypeRecordがユーザーエージェントによってサポートされていない場合は、falseを返します。
次のいずれかがtrueである場合:
destinationが"audio"または"video"であり、mimeTypeRecordがオーディオまたはビデオMIMEタイプである場合;
destinationがスクリプトに似た宛先であり、mimeTypeRecordがJavaScript MIMEタイプである場合;
destinationが"image"であり、mimeTypeRecordがイメージMIMEタイプである場合;
destinationが"font"であり、mimeTypeRecordがフォントMIMEタイプである場合;
destinationが"json"であり、mimeTypeRecordがJSON MIMEタイプである場合;
その場合はtrueを返します。
falseを返します。
プリロードキーを作成するために、リクエスト requestを指定し、新しいプリロードキーを返します。このキーのURLはrequestのURL、宛先はrequestの宛先、モードはrequestのモード、そして資格情報モードはrequestの資格情報モードになります。
文字列destinationを指定してプリロード宛先を変換するために:
もしdestinationが"fetch"、"font"、"image"、"script"、"style"、または"track"でない場合は、nullを返します。
変換結果を返します。
リンク処理オプション optionsと、レスポンスを受け入れるアルゴリズムprocessResponseをオプションとして指定してプリロードするために:
もしoptionsの宛先が"image"であり、optionsのソースセットがnullでない場合、optionsのhrefをソースセットから画像ソースを選択する結果に設定します。
requestをリンクリクエストを作成する結果とします。
もしrequestがnullの場合、returnします。
unsafeEndTimeを0に設定します。
keyをプリロードキーを作成する結果とします。
もしoptionsのドキュメントが"pending"である場合、requestのイニシエータタイプを"early hint"に設定します。
controllerをnullに設定します。
reportTimingを、ドキュメント
documentに対して、controllerにタイミングを報告するためのものとします。
controllerを、requestをフェッチする結果とし、以下のステップに従ってprocessResponseConsumeBodyを設定します。responseを、null、失敗、またはバイトシーケンス bodyBytesとします:
もしbodyBytesがバイトシーケンスである場合、responseのボディをbodyBytesのボディとして設定します。
processResponseConsumeBodyを使用することにより、ボディ全体をネットワークからロードするようにしています。これは、プリロードが消費されるかどうか(現時点では不確定です)にかかわらず、プリローダがネットワークからボディ全体をロードすることを保証するために必要です。このステップでは、リクエストのボディを新しいボディにリセットし、同じバイトを含むようにします。これにより、他の仕様が実際に消費されるときにボディを読み取ることができます。
それ以外の場合は、responseをネットワークエラーに設定します。
unsafeEndTimeを安全でない共有現在時刻に設定します。
もしoptionsのドキュメントがnullでない場合、reportTimingをoptionsのドキュメントに対して呼び出します。
もしentryのレスポンスが利用可能なときがnullである場合、entryのレスポンスをresponseに設定します。そうでなければ、entryのレスポンスが利用可能なときを使用してresponseを呼び出します。
もしprocessResponseが指定されている場合、responseを使用してprocessResponseを呼び出します。
commitを、ドキュメント
documentに対して以下のステップを行うものとします:
もしentryのレスポンスがnullでない場合、documentに対してreportTimingを呼び出します。
documentのプリロードされたリソースのマップ[key]をentryに設定します。
もしoptionsのドキュメントがnullである場合、optionsのドキュメント準備完了時をcommitに設定します。それ以外の場合は、optionsのドキュメントを使用してcommitを呼び出します。
この種類のリンクリソースに対するリンクリソースをフェッチして処理する手順は、リンク要素elを与えられたときに行います:
elのためにソースセットを更新する。
optionsを要素からリンクオプションを作成する結果とします。
リンクヘッダーを処理する手順は、この種類のリンクリソースに対して、リンク処理オプション optionsを指定して、プリロード optionsします。
privacy-policy"privacy-policy
キーワードは、link、a、および area
要素と共に使用できます。このキーワードは、ハイパーリンクを作成します。
privacy-policy
キーワードは、参照される文書が、現在の文書に適用されるデータ収集および使用の実践に関する情報を含むことを示します。詳細は Additional Link Relation Types
に記載されています。参照される文書は、スタンドアロンのプライバシーポリシーまたは、より一般的な文書の特定のセクションである可能性があります。[RFC6903]
search"search キーワードは、link、a、area、および form 要素と共に使用できます。このキーワードは、ハイパーリンクを作成します。
search
キーワードは、参照される文書が、文書および関連リソースを検索するためのインターフェースを提供することを示します。
OpenSearch記述文書は、link
要素およびsearchリンクタイプと共に使用して、ユーザーエージェントが検索インターフェースを自動的に発見できるようにすることができます。[OPENSEARCH]
stylesheet"
stylesheet
キーワードは、link
要素と共に使用されます。このキーワードは、スタイリング処理モデルに貢献する外部リソースリンクを作成します。このキーワードは
body-ok です。
指定されたリソースは、ドキュメントの表示方法を記述するCSSスタイルシート です。
サポートは1つのエンジンのみ。
もしalternate キーワードが
link
要素にも指定されている場合、そのリンクは代替スタイルシートとなります。この場合、title 属性が
link
要素に指定されていなければならず、値は空であってはいけません。
stylesheet
キーワードで指定されたリソースのデフォルトタイプは、text/css です。
このタイプのlink要素は、その要素が暗黙的に潜在的なレンダーブロックであり、要素がそのノードドキュメントのパーサーによって作成された場合に適用されます。
disabled 属性がlink 要素にセットされ、stylesheet
キーワードが設定されている場合、関連するCSSスタイルシートを無効にします。
このタイプのリンクを取得して処理するのに適切なタイミングは以下の通りです:
外部リソースリンクが、既にブラウジングコンテキストに接続されているlink要素に作成されたとき。
既にブラウジングコンテキストに接続されているlink要素のhref属性が変更されたとき。
link要素の外部リソースリンクが既にブラウジングコンテキストに接続されている場合に、そのdisabled属性が設定、変更、または削除されます。
既にブラウジングコンテキストに接続されているlink要素のcrossorigin属性が設定、変更、または削除されたとき。
既にブラウジングコンテキストに接続されているlink要素のtype属性が、以前に取得された外部リソースのContent-Typeメタデータと一致しない、または一致しなくなった値に設定または変更されたとき。
以前はサポートされていないタイプを指定したために取得されなかったが、既にブラウジングコンテキストに接続されているlink要素のtype属性が削除または変更されたとき。
既にブラウジングコンテキストに接続されている外部リソースリンクが、代替スタイルシートからそうでないものに、またはその逆に変更されたとき。
注意: ドキュメントがクイークモードに設定され、外部リソースの同一オリジンと一致し、外部リソースのContent-Typeメタデータがサポートされていないスタイルシートタイプである場合、ユーザーエージェントは代わりにそれをtext/cssと見なさなければなりません。
リンクされたリソースのフェッチ設定ステップは、リンク要素elおよびリクエストrequestが与えられた場合に適用されます:
もしelのdisabled属性が設定されている場合、falseを返します。
もしelがスクリプトブロックスタイルシートに貢献している場合、elをそのノードドキュメントのスクリプトブロックスタイルシートセットに追加します。
もしelのmedia属性の値が環境に一致し、elが潜在的にレンダーブロックされる場合、elでレンダリングをブロックします。
trueを返します。
CSSOMのCSSスタイルシートを取得するアルゴリズムをissue #968に示された計画に基づき、デフォルトのリソース取得と処理アルゴリズムの代わりに使用する予定です。それまでの間、すべての重要なサブリソースに対するリクエストは、link要素が現在レンダーブロックしているかどうかに基づいて、そのレンダーブロックが設定されるべきです。
このタイプのリンクされたリソースを処理するには、リンク要素el、ブール値success、レスポンスresponse、およびバイトシーケンスbodyBytesが与えられます:
リソースのContent-Typeメタデータがtext/cssでない場合、successをfalseに設定します。
もしelがもはやスタイリング処理モデルに貢献する外部リソースリンクを作成しない場合、または、当該リソースが取得されてから再度取得する必要が生じた場合は:
リストからelを削除し、elのノードドキュメントのスクリプトブロックスタイルシートセットから削除します。
戻ります。
もしelが関連するCSSスタイルシートを持っている場合、そのCSSスタイルシートを削除します。
もしsuccessがtrueであれば:
responseのURLリスト[0]
ここでURLを提供するのは、w3c/csswg-drafts issue #9316が修正されることを前提としています。
el
elのmedia属性。
これは、現在は存在しない可能性のある属性への参照であり、現在の属性値のコピーではありません。CSSOMでは、属性が動的に設定、変更、または削除された場合の動作が定義されています。
もしelがドキュメントツリー内にある場合はelのtitle属性、そうでない場合は空文字列。
これも同様に、属性の現在の値のコピーではなく、属性への参照です。
リンクが代替スタイルシートであり、elの明示的に有効がfalseである場合は設定され、それ以外の場合は解除されます。
リソースがCORS-同一オリジンである場合に設定され、それ以外の場合は解除されます。
null
デフォルト値のままにします。
未初期化のままにします。
これは正しくないように思えます。おそらくbodyBytesを使用すべきですか?issue #2997で追跡しています。
CSS 環境エンコーディングは、次の手順を実行した結果です: [CSSSYNTAX]
もしelがcharset属性を持っている場合、その属性の値からエンコーディングを取得します。成功した場合は、結果のエンコーディングを返します。[ENCODING]
そうでない場合は、ドキュメントの文字エンコーディングを返します。[DOM]
もしelがスクリプトブロックスタイルシートに貢献している場合は:
確認: elのノードドキュメントのスクリプトブロックスタイルシートセットがelを含んでいることを確認します。
リストからelを削除します。それをノードドキュメントのスクリプトブロックスタイルシートセットから削除します。
リンクヘッダーを処理するためのステップは、このタイプのリンクされたリソースには何も行わないことです。
tag"tag キーワードは、a および area 要素と共に使用されます。このキーワードはハイパーリンクを作成します。
tag
キーワードは、参照されたドキュメントが表すtagが現在のドキュメントに適用されることを示します。
このキーワードは、タグが現在のドキュメントに適用されることを示すため、複数のページにわたる人気のタグをリストするタグクラウドのマークアップに使用するのは不適切です。
このドキュメントは宝石に関するものであり、そのために "https://en.wikipedia.org/wiki/Gemstone"
というタグが付けられています。これにより、米国の町、Rubyパッケージ形式、またはスイスの機関車クラスではなく、「宝石」タイプの宝石に適用されることが明確に分類されています。
<!DOCTYPE HTML>
< html lang = "en" >
< head >
< title > My Precious</ title >
</ head >
< body >
< header >< h1 > My precious</ h1 > < p > Summer 2012</ p ></ header >
< p > Recently I managed to dispose of a red gem that had been
bothering me. I now have a much nicer blue sapphire.</ p >
< p > The red gem had been found in a bauxite stone while I was digging
out the office level, but nobody was willing to haul it away. The
same red gem stayed there for literally years.</ p >
< footer >
タグ: < a rel = tag href = "https://en.wikipedia.org/wiki/Gemstone" > Gemstone</ a >
</ footer >
</ body >
</ html >
このドキュメントでは、2つの記事があります。しかし、「tag」リンクはページ全体に適用されます(このリンクがどこに配置されても、記事要素内に配置されていても適用されます)。
<!DOCTYPE HTML>
< html lang = "en" >
< head >
< title > Gem 4/4</ title >
</ head >
< body >
< article >
< h1 > 801: シュタインボック</ h1 >
< p > 801号Gem 4/4電気ディーゼルはアイベックスがあり、2002年に再建されました。</ p >
</ article >
< article >
< h1 > 802: マーモット</ h1 >
< figure >
< img src = "https://upload.wikimedia.org/wikipedia/commons/b/b0/Trains_de_la_Bernina_en_hiver_2.jpg" alt = "802号はパンタグラフと側面に高い換気口があり、赤かった。" >
< figcaption > 1980年代、ラーゴ・ビアンコ上の802号。</ figcaption >
</ figure >
< p > 802号Gem 4/4電気ディーゼルはマーモットがあり、2003年に再建されました。</ p >
</ article >
< p class = "topic" >< a rel = tag href = "https://en.wikipedia.org/wiki/Rhaetian_Railway_Gem_4/4" > Gem 4/4</ a ></ p >
</ body >
</ html >
terms-of-service"terms-of-service
キーワードは、link、a、およびarea要素と共に使用できます。このキーワードはハイパーリンクを作成します。
terms-of-service
キーワードは、参照されたドキュメントが、現在のドキュメントの提供者と、現在のドキュメントを使用しようとするユーザーとの間の契約に関する情報を含んでいることを示します。詳細については、Additional Link
Relation Typesを参照してください。[RFC6903]
いくつかのドキュメントは、ドキュメントのシーケンスの一部を形成します。
ドキュメントのシーケンスとは、各ドキュメントが前の兄弟と次の兄弟を持つことができるものです。前の兄弟がないドキュメントはそのシーケンスの開始であり、次の兄弟がないドキュメントはそのシーケンスの終了です。
ドキュメントは複数のシーケンスの一部である場合があります。
next"next キーワードは、link、a、area、およびform要素と共に使用できます。このキーワードはハイパーリンクを作成します。
next
キーワードは、ドキュメントがシーケンスの一部であり、リンクがシーケンス内の次の論理ドキュメントに導くことを示します。
next キーワードがlink要素で使用される場合、ユーザーエージェントは、そのようなリンクをdns-prefetch、preconnect、またはprefetchキーワードの1つを使用しているかのように処理する必要があります。ユーザーエージェントが使用するキーワードは実装に依存します。たとえば、ユーザーエージェントがデータ、バッテリー電力、または処理能力を節約しようとしている場合は、コストの低いpreconnect処理モデルを使用したいかもしれませんし、同様のシナリオにおける過去のユーザー行動のヒューリスティック分析に基づいてキーワードを選択したいかもしれません。
prev"prev キーワードは、link、a、area、およびform要素と共に使用できます。このキーワードはハイパーリンクを作成します。
prev
キーワードは、ドキュメントがシーケンスの一部であり、リンクがシーケンス内の前の論理ドキュメントに導くことを示します。
同義語: 歴史的な理由から、ユーザーエージェントは"previous"というキーワードもprevキーワードと同様に扱う必要があります。
定義済みのリンクタイプセットへの拡張は、既存のrel値のためのマイクロフォーマットページで登録できます。[MFREL]
誰でもいつでも既存のrel値のためのマイクロフォーマットページを編集して、タイプを追加することができます。拡張タイプには、次の情報を指定する必要があります。
定義される実際の値。値は他の定義された値と紛らわしくないものでなければなりません(例: 大文字小文字の違いだけで異なる値)。
値にU+003Aコロン文字(:)が含まれている場合、それは絶対URLでなければなりません。
linkに対して
次のうちの1つ:
link要素に指定してはなりません。
link要素に指定できます。それはハイパーリンクを作成します。
link要素に指定できます。それは外部リソースリンクを作成します。
aおよびareaに対して
次のうちの1つ:
aおよびarea要素に指定してはなりません。
aおよびarea要素に指定できます。それはハイパーリンクを作成します。
aおよびarea要素に指定できます。それは外部リソースリンクを作成します。
aおよびarea要素に指定できます。それは、要素によって作成された他のハイパーリンクに注釈を付けます。
formに対して
次のうちの1つ:
form要素に指定してはなりません。
form要素に指定できます。それはハイパーリンクを作成します。
form要素に指定できます。それは外部リソースリンクを作成します。
form要素に指定できます。それは、要素によって作成された他のハイパーリンクに注釈を付けます。
キーワードの意味に関する非規範的な短い説明。
キーワードの意味と要件の詳細な説明へのリンク。それは、wikiの他のページへのリンク、または外部ページへのリンクである可能性があります。
処理要件が完全に同じである他のキーワード値のリスト。作成者は同義語として定義された値を使用すべきではありません。これらはあくまでレガシーコンテンツのサポートのためにユーザーエージェントがサポートすることを意図しています。誰でも実際に使用されていない同義語を削除することができます。このようにして、レガシーコンテンツとの互換性のために処理される必要がある名前だけが登録されるべきです。
次のうちの1つ:
キーワードが既存の値と重複していることが判明した場合、それは削除され、既存の値の同義語としてリストされるべきです。
提案中の状態で1か月以上使用されておらず、または指定されていない場合、そのキーワードはレジストリから削除される可能性があります。
提案中の状態で追加されたキーワードが既存の値と重複していることが判明した場合、それは削除され、既存の値の同義語としてリストされるべきです。提案中の状態で追加されたキーワードが有害であると判明した場合、それは「中止」ステータスに変更されるべきです。
誰でもいつでもステータスを変更できますが、上記の定義に従ってのみ行うべきです。
準拠チェッカーは、既存のrel値のためのマイクロフォーマットページで提供されている情報を使用して、値が許可されているかどうかを確認する必要があります。この仕様で定義された値、または「提案中」または「承認済み」とマークされた値は、「効果...」フィールドに記載されている要素で使用された場合、受け入れられる必要がありますが、この仕様で定義されていない値や、前述のページにリストされていない値は無効として拒否されなければなりません。準拠チェッカーは、この情報をキャッシュすることができます(例: パフォーマンス上の理由や信頼性の低いネットワーク接続の使用を避けるため)。
著者がこの仕様やwikiページで定義されていない新しいタイプを使用する場合、準拠チェッカーは上記の詳細を使用して、その値を「提案中」ステータスでwikiに追加することを提案するべきです。
既存のrel値のためのマイクロフォーマットページで「提案中」または「承認済み」のステータスを持つ拡張として定義されたタイプは、rel属性をlink、a、およびarea要素で「効果...」フィールドに従って使用することができます。[MFREL]
ins 要素すべての現在のエンジンでサポートされています。
cite — 引用元や編集に関する詳細情報へのリンク
datetime — 変更の日時(オプション)
HTMLModElement を使用します。
ins 要素は文書への追加を表します。
次の例は、1 つの段落の追加を表します:
< aside >
< ins >
< p > 私は果物が好きです。 </ p >
</ ins >
</ aside >
次の例も同様です。ここでは、aside
要素内のすべての内容が
フレージングコンテンツと見なされるため、段落は 1 つだけです:
< aside >
< ins >
りんごは < em > おいしい</ em > 。
</ ins >
< ins >
梨もそうです。
</ ins >
</ aside >
次の例では、2 つの段落が追加され、そのうち 2 番目の段落は 2 部に分けて挿入されています。この例の最初の ins 要素は
段落の境界を超えており、これは望ましくない形式と見なされます。
< aside >
<!-- これは避けるべきです -->
< ins datetime = "2005-03-16 00:00Z" >
< p > 私は果物が好きです。 </ p >
りんごは < em > おいしい</ em > 。
</ ins >
< ins datetime = "2007-12-19 00:00Z" >
梨もそうです。
</ ins >
</ aside >
これをより適切にマークアップする方法を示します。要素は増えますが、どの要素も暗黙的な段落の境界を超えていません。
< aside >
< ins datetime = "2005-03-16 00:00Z" >
< p > 私は果物が好きです。 </ p >
</ ins >
< ins datetime = "2005-03-16 00:00Z" >
りんごは < em > おいしい</ em > 。
</ ins >
< ins datetime = "2007-12-19 00:00Z" >
梨もそうです。
</ ins >
</ aside >
del
要素すべての現在のエンジンでサポートされています。
cite — 引用元や編集に関する詳細情報へのリンク
datetime — 変更の日時(オプション)
HTMLModElement を使用します。
del 要素は文書からの削除を表します。
次の例は、「やること」リストを示しており、完了した項目が完了日時と共に取り消し線で表示されています。
< h1 > やること</ h1 >
< ul >
< li > 食器洗い機を空にする</ li >
< li >< del datetime = "2009-10-11T01:25-07:00" > ウォルター・ルウィンの講義を見る</ del ></ li >
< li >< del datetime = "2009-10-10T23:38-07:00" > さらにトラックをダウンロードする</ del ></ li >
< li > プリンターを買う</ li >
</ ul >
ins
要素と
del
要素に共通する属性
cite 属性は、変更を説明する文書の
URL を指定するために使用できます。その文書が長い場合、たとえば会議の議事録の場合、
著者は変更について説明している特定の部分を指すフラグメントを含めることが推奨されます。
もし cite
属性が存在する場合、それは変更を説明する
有効な URL であり、
かつスペースで囲まれている可能性があります。対応する引用リンクを取得するには、属性の値を要素の
ノード文書に対して
解析する必要があります。
ユーザーエージェントは、そのような引用リンクをユーザーがたどることを許可するかもしれませんが、それらは主にプライベート用途(例:サイトの編集についての統計を収集するサーバーサイドスクリプトによって)を目的としています。
datetime
属性は、変更の日時を指定するために使用できます。
もし存在する場合、datetime
属性の値は
有効な日時文字列でなければなりません。
ユーザーエージェントは datetime
属性を
日付または時間の文字列を解析するアルゴリズムに従って解析しなければなりません。
もしそれが日付またはグローバル日時を返さない場合、
その変更には関連するタイムスタンプがありません(値は非準拠です。有効な日時文字列ではありません)。
それ以外の場合、変更は指定された日付またはグローバル日時に行われたものと見なされます。もし指定された値がグローバル日時である場合、ユーザーエージェントは関連するタイムゾーンオフセット情報を使用して指定された日時を表示するタイムゾーンを決定するべきです。
この値はユーザーに表示される場合がありますが、主にプライベート用途を目的としています。
ins
要素と del
要素は、HTMLModElement
インターフェイスを実装しなければなりません:
すべての現在のエンジンでサポートされています。
[Exposed =Window ]
interface HTMLModElement : HTMLElement {
[HTMLConstructor ] constructor ();
[CEReactions ] attribute USVString cite ;
[CEReactions ] attribute DOMString dateTime ;
};
cite IDL 属性は、要素の
cite
コンテンツ属性を反映しなければなりません。
dateTime IDL
属性は、要素の
datetime
コンテンツ属性を反映しなければなりません。
このセクションは規範的ではありません。
ins 要素と del 要素は段落構造に影響を与えないため、明示的な
p 要素がなく
段落が暗黙的に解釈される場合、一つの ins または del 要素が、全体の段落やその他の
非フレージングコンテンツ要素、および別の段落の一部をまたがることがあります。例えば以下のように:
< section >
< ins >
< p >
これは挿入された段落です。
</ p >
これは、上記の段落と同時に挿入された別の段落の最初の文です。
</ ins >
これは、もともとあった2番目の文です。
</ section >
一部の段落を p 要素で包むことで、同じ ins または del
要素で、1つの段落の終わり、2つ目の段落全体、および3つ目の段落の始まりをカバーすることさえ可能です(ただし、これは非常に紛らわしく、良い実践とは見なされません):
< section >
これは最初の段落です。 < ins > この文が挿入されました。
< p > この2番目の段落が挿入されました。</ p >
この文も挿入されました。</ ins > これは、この例の3つ目の段落です。
<!-- (これはしないでください) -->
</ section >
しかし、暗黙的な段落が定義されている方法により、1つの段落の終わりと次の段落の始まりを同じ ins または del
要素でマークアップすることはできません。その代わりに、1つ(または2つ)の p 要素と2つの ins または
del 要素を使用する必要があります。例えば次のように:
< section >
< p > これは最初の段落です。 < del > この文が削除されました。</ del ></ p >
< p >< del > この文も削除されました。</ del > この文には別の < del> 要素が必要でした。</ p >
</ section >
上記の混乱も一因であるため、著者は常にすべての段落を p
要素でマークアップし、ins や del 要素が
暗黙的な段落の境界を越えないようにすることが強く推奨されます。
このセクションは規範的ではありません。
ol 要素と ul 要素のコンテンツモデルは、ins および del
要素を子要素として許可していません。リストは、削除としてマークされた項目も含めて、常にすべての項目を表します。
項目が挿入または削除されたことを示すために、ins または
del 要素を li
要素の内容の周りに包むことができます。項目が別の項目に置き換えられたことを示すために、単一の li 要素に1つ以上の del 要素を配置し、その後に1つ以上の ins 要素を続けることができます。
次の例では、空の状態で始まったリストに項目が追加され、時間とともに削除されました。強調表示された部分は、リストの「現在」の状態を示しています。ただし、リスト項目の番号は編集を考慮していません。
< h1 > ストップシップバグ</ h1 >
< ol >
< li >< ins datetime = "2008-02-12T15:20Z" > バグ 225: 雪で雨センサーが作動しない</ ins ></ li >
< li >< del datetime = "2008-03-01T20:22Z" >< ins datetime = "2008-02-14T12:02Z" > バグ 228: 4月にウォーターバッファがオーバーフローする</ ins ></ del ></ li >
< li >< ins datetime = "2008-02-16T13:50Z" > バグ 230: 給湯器が再生可能燃料を使用しない</ ins ></ li >
< li >< del datetime = "2008-02-20T21:15Z" >< ins datetime = "2008-02-16T14:25Z" > バグ 232: 起動後に二酸化炭素排出が検出される</ ins ></ del ></ li >
</ ol >
次の例では、果物だけが含まれていたリストが、色だけのリストに置き換えられました。
< h1 > </ del > 果物リスト</ del >< ins > 色リスト</ ins ></ h1 >
< ul >
< li >< del > ライム</ del >< ins > グリーン</ ins ></ li >
< li >< del > リンゴ</ del ></ li >
< li > オレンジ</ li >
< li >< del > ナシ</ del ></ li >
< li >< ins > ティール</ ins ></ li >
< li >< del > レモン</ del ></ ins > イエロー</ ins ></ li >
< li > オリーブ</ li >
< li >< ins > パープル</ ins ></ li >
</ ul >
このセクションは規範的ではありません。
テーブルモデルの一部を構成する要素には、ins および del
要素を許可しない複雑なコンテンツモデル要件があるため、テーブルへの編集を示すことは難しい場合があります。
行全体または列全体が追加または削除されたことを示すために、その行または列内の各セルの内容全体を ins または del 要素で包むことができます。
ここでは、テーブルの行が追加されています:
< table >
< thead >
< tr > < th > ゲーム名 < th > ゲームパブリッシャー < th > 評価
< tbody >
< tr > < td > Diablo 2 < td > Blizzard < td > 8/10
< tr > < td > Portal < td > Valve < td > 10/10
< tr > < td > < ins > Portal 2</ ins > < td > < ins > Valve</ ins > < td > < ins > 10/10</ ins >
</ table >
ここでは、列が削除されています(削除された時間と、それを説明するページへのリンクも示されています):
< table >
< thead >
< tr > < th > ゲーム名 < th > ゲームパブリッシャー < th > < del cite = "/edits/r192" datetime = "2011-05-02 14:23Z" > 評価</ del >
< tbody >
< tr > < td > Diablo 2 < td > Blizzard < td > < del cite = "/edits/r192" datetime = "2011-05-02 14:23Z" > 8/10</ del >
< tr > < td > Portal < td > Valve < td > < del cite = "/edits/r192" datetime = "2011-05-02 14:23Z" > 10/10</ del >
</ table >
一般的に言って、より複雑な編集(例: セルが削除され、その後すべてのセルが上または左に移動されたことを示すなど)を示す良い方法はありません。
picture
要素すべての現在のエンジンでサポートされています。
すべての現在のエンジンでサポートされています。
source
要素に続いて、1つの img 要素が続く。スクリプトサポート要素と混在することもある。
[Exposed =Window ]
interface HTMLPictureElement : HTMLElement {
[HTMLConstructor ] constructor ();
};
picture 要素は、含まれている img
要素に対して複数のソースを提供するコンテナです。これにより、著者はスクリーンピクセル密度、ビューポートサイズ、画像形式、その他の要因に基づいて、使用する画像リソースについてユーザーエージェントに宣言的に制御やヒントを与えることができます。要素はその子要素を表します。
picture
要素は、似たような外見を持つ video 要素や
audio 要素とは少し異なります。これらすべてには
source
要素が含まれていますが、source 要素の
src 属性は、picture
要素内にネストされている場合は意味を持ちません。また、リソース選択アルゴリズムも異なります。さらに、picture
要素自体は何も表示しません。単に、その中に含まれている img 要素に対して、複数の URL
から選択できるコンテキストを提供するだけです。
source 要素すべての現在のエンジンでサポートされています。
すべての現在のエンジンでサポートされています。
picture
要素の子要素として、img 要素の前に。
track 要素の前に。
type — 埋め込みリソースのタイプ
media — 適用されるメディア
src (audio または video 内) — リソースのアドレス
srcset (picture 内) —
高解像度ディスプレイや小型モニタなど、異なる状況で使用する画像
sizes (picture 内) —
異なるページレイアウト用の画像サイズ
width (picture 内) — 水平方向の寸法
height (picture 内) — 垂直方向の寸法
[Exposed =Window ]
interface HTMLSourceElement : HTMLElement {
[HTMLConstructor ] constructor ();
[CEReactions ] attribute USVString src ;
[CEReactions ] attribute DOMString type ;
[CEReactions ] attribute USVString srcset ;
[CEReactions ] attribute DOMString sizes ;
[CEReactions ] attribute DOMString media ;
[CEReactions ] attribute unsigned long width ;
[CEReactions ] attribute unsigned long height ;
};
source 要素は、img 要素に対して複数の代替 ソースセットを指定したり、メディア要素に対して複数の代替 メディアリソースを指定したりすることができます。これは単独では何も表しません。
type
属性は存在する場合があります。存在する場合、値は 有効な MIME
タイプ文字列 でなければなりません。
media
属性も存在する場合があります。存在する場合、値には 有効なメディアクエリリスト が含まれている必要があります。ユーザーエージェントは、その値が環境に一致しない場合、次の source 要素にスキップします。
media 属性は、メディア要素のリソース選択アルゴリズム中に一度だけ評価されます。対照的に、picture
要素を使用する場合、ユーザーエージェントは環境の変化に対応します。
残りの要件は、親が picture
要素か、メディア要素かによって異なります:
source 要素の親が picture 要素の場合
srcset
属性が存在しなければなりません。また、srcset 属性です。
srcset 属性は、source
要素が選択された場合に、ソースセットに 画像ソースを提供します。
もし srcset 属性に 画像候補文字列が幅記述子を使用して存在する場合、sizes
属性も存在する場合があります。さらに、次の兄弟 img 要素が自動サイズを許可しない場合、sizes
属性が存在しなければなりません。sizes 属性は sizes 属性であり、source
要素が選択された場合、ソースサイズを ソースセットに提供します。
もし img 要素が自動サイズを許可する場合、先行する兄弟 source 要素には sizes
属性を省略することができます。このような場合、auto を指定したのと同等です。
source 要素は 寸法属性をサポートします。img 要素は、source 要素の width と height
属性を使用して、そのレンダリング寸法とアスペクト比を決定できます。レンダリングのセクションで定義されているように。
type 属性は、ソースセット内の画像のタイプを指定し、ユーザーエージェントが指定されたタイプをサポートしていない場合、次の source
要素にスキップできるようにします。
もし type
属性が指定されていない場合、ユーザーエージェントは画像フォーマットを取得した後、それをサポートしていないと判明しても、別の source 要素を選択しません。
source 要素が次の兄弟
source 要素または
img 要素を持ち、srcset
属性が指定されている場合、少なくとも次のいずれかを持っていなければなりません:
media
属性が指定され、その値が 前後の ASCII
ホワイトスペースを除去した後、空の文字列でなく、かつ "all" という文字列と ASCII 大文字小文字を区別しない 一致を持たない。
type
属性が指定されている。
src 属性は存在してはなりません。
source 要素の親が メディア要素の場合
src 属性は、URL
をメディアリソースに指定します。その値は 有効な非空 URL
で、前後にスペースが含まれている可能性があります。この属性は存在しなければなりません。
type 属性は メディアリソース のタイプを指定し、ユーザーエージェントがこの メディアリソース
を取得する前に再生可能かどうかを判断するのに役立ちます。特定の MIME タイプが定義する codecs
パラメータは、リソースのエンコード方法を正確に指定するために必要な場合があります。[RFC6381]
source 要素の src または type 属性を、要素がすでに video または audio
要素に挿入されているときに動的に変更しても効果はありません。再生内容を変更するには、単に メディア要素 に直接 src
属性を使用し、利用可能なリソースから選択するために canPlayType()
メソッドを使用することが考えられます。一般的に、ドキュメントが解析された後で source
要素を手動で操作するのは不必要に複雑なアプローチです。
以下のリストには、codecs= MIME パラメータを type
属性で使用するいくつかの例が示されています。
< source src = 'video.mp4' type = 'video/mp4; codecs="avc1.42E01E, mp4a.40.2"' >
< source src = 'video.mp4' type = 'video/mp4; codecs="avc1.58A01E, mp4a.40.2"' >
< source src = 'video.mp4' type = 'video/mp4; codecs="avc1.4D401E, mp4a.40.2"' >
< source src = 'video.mp4' type = 'video/mp4; codecs="avc1.64001E, mp4a.40.2"' >
< source src = 'video.mp4' type = 'video/mp4; codecs="mp4v.20.8, mp4a.40.2"' >
< source src = 'video.mp4' type = 'video/mp4; codecs="mp4v.20.240, mp4a.40.2"' >
< source src = 'video.3gp' type = 'video/3gpp; codecs="mp4v.20.8, samr"' >
< source src = 'video.ogv' type = 'video/ogg; codecs="theora, vorbis"' >
< source src = 'video.ogv' type = 'video/ogg; codecs="theora, speex"' >
< source src = 'audio.ogg' type = 'audio/ogg; codecs=vorbis' >
< source src = 'audio.spx' type = 'audio/ogg; codecs=speex' >
< source src = 'audio.oga' type = 'audio/ogg; codecs=flac' >
< source src = 'video.ogv' type = 'video/ogg; codecs="dirac, vorbis"' >
source HTML要素挿入手順は、insertedNodeの場合は以下の通りです。
insertedNodeの親がsrc属性を持たず、networkStateがNETWORK_EMPTYの値を持つ
メディア要素である場合、そのメディア要素のリソース選択アルゴリズムを実行します。
insertedNodeの次の兄弟がimg要素であり、その親がpicture要素である場合、これをimg要素に対する関連する変異としてカウントします。
source HTML要素削除手順は、removedNodeとoldParentの場合は以下の通りです。
IDL属性src、type、srcset、sizesおよびmediaは、それぞれの名前の対応する内容属性を反映しなければなりません。
提供されたメディアリソースがすべてのユーザーエージェントでレンダリングできるかどうかを著者が確信していない場合、著者は最後のエラーイベントをsource要素でリッスンし、フォールバック動作をトリガーすることができます。
< script >
function fallback( video) {
// <video> の内容で置き換える
while ( video. hasChildNodes()) {
if ( video. firstChild instanceof HTMLSourceElement)
video. removeChild( video. firstChild);
else
video. parentNode. insertBefore( video. firstChild, video);
}
video. parentNode. removeChild( video);
}
</ script >
< video controls autoplay >
< source src = 'video.mp4' type = 'video/mp4; codecs="avc1.42E01E, mp4a.40.2"' >
< source src = 'video.ogv' type = 'video/ogg; codecs="theora, vorbis"'
onerror = "fallback(parentNode)" >
...
</ video >
img 要素すべての現行エンジンでサポート。
すべての現行エンジンでサポート。
usemap 属性がある場合:
インタラクティブコンテンツ。
source 要素の後で、 picture 要素の子として。
alt — 画像が利用できない場合に使用する代替テキスト
src — リソースのアドレス
srcset —
高解像度ディスプレイ、小型モニターなど、さまざまな状況で使用する画像
sizes — 異なるページレイアウトの画像サイズ
crossorigin —
この要素がクロスオリジンリクエストを処理する方法
usemap — 使用するイメージマップの名前
ismap — 画像がサーバーサイドイメージマップであるかどうか
width — 水平次元
height — 垂直次元
referrerpolicy
— この要素によって開始されたフェッチのリファラーポリシー
decoding —
プレゼンテーション用にこの画像を処理するときに使用するデコードのヒント
loading — ローディングの延期を決定するときに使用
fetchpriority —
この要素によって開始されたフェッチの優先度を設定します
alt 属性がある場合: 著者向け; 実装者向け。
[Exposed =Window ,
LegacyFactoryFunction =Image (optional unsigned long width , optional unsigned long height )]
interface HTMLImageElement : HTMLElement {
[HTMLConstructor ] constructor ();
[CEReactions ] attribute DOMString alt ;
[CEReactions ] attribute USVString src ;
[CEReactions ] attribute USVString srcset ;
[CEReactions ] attribute DOMString sizes ;
[CEReactions ] attribute DOMString ? crossOrigin ;
[CEReactions ] attribute DOMString useMap ;
[CEReactions ] attribute boolean isMap ;
[CEReactions ] attribute unsigned long width ;
[CEReactions ] attribute unsigned long height ;
readonly attribute unsigned long naturalWidth ;
readonly attribute unsigned long naturalHeight ;
readonly attribute boolean complete ;
readonly attribute USVString currentSrc ;
[CEReactions ] attribute DOMString referrerPolicy ;
[CEReactions ] attribute DOMString decoding ;
[CEReactions ] attribute DOMString loading ;
[CEReactions ] attribute DOMString fetchPriority ;
Promise <undefined > decode ();
// also has obsolete members
};
img 要素は画像を表します。
img 要素には、最初に要素自体に設定される寸法属性ソースがあります。
すべての現行エンジンでサポート。
すべての現行エンジンでサポート。
src属性およびsrcset属性、そして親がpicture要素である場合に、前の兄弟要素であるsource要素のsrcset属性に指定された画像が埋め込みコンテンツです。alt属性の値は、画像を処理できない人や画像の読み込みを無効にしている人のために同等のコンテンツを提供します(つまり、これはimg要素のフォールバックコンテンツです)。
alt属性の値に関する要件は、別のセクションで説明されています。
src属性は必須であり、有効な非空のURLで、スペースに囲まれている可能性のある非インタラクティブでオプションでアニメーション化された画像リソースを参照し、ページングもスクリプト化もされていない必要があります。
上記の要件は、画像が静的なビットマップ(例:PNG、GIF、JPEG)、単一ページのベクタードキュメント(単一ページのPDF、SVGドキュメント要素を含むXMLファイル)、アニメーション化されたビットマップ(APNG、アニメーションGIF)、アニメーション化されたベクターグラフィックス(宣言型SMILアニメーションを使用するSVGドキュメント要素を含むXMLファイル)などであることを意味します。しかし、これらの定義は、スクリプトを含むSVGファイル、複数ページのPDFファイル、インタラクティブなMNGファイル、HTMLドキュメント、プレーンテキストドキュメントなどを除外します。[PNG] [GIF] [JPEG] [PDF] [XML] [APNG] [SVG] [MNG]
srcset属性も存在する場合があります。これはsrcset属性です。
srcset属性とsrc属性(幅の記述子が使用されていない場合)は、画像ソースをソースセットに提供します(source要素が選択されていない場合)。
もしsrcset属性が存在し、画像候補文字列が幅の記述子を使用している場合は、sizes属性も存在しなければなりません。srcset属性が指定されておらず、loading属性がLazy状態にある場合、sizes属性を「auto」という値で指定することができます(ASCII大文字小文字を区別しない)。sizes属性はsizes属性であり、ソースサイズをソースセットに提供します(source要素が選択されていない場合)。
img要素は、以下の条件を満たす場合に自動サイズを許可します:
loading 属性が遅延状態にある場合sizes 属性の値が "auto"
(ASCII 大文字小文字を区別しない) または "auto," (ASCII 大文字小文字を区別しない) で始まる場合すべての現行エンジンでサポート。
crossorigin 属性はCORS
設定属性です。その目的は、クロスオリジンアクセスを許可するサードパーティサイトの画像を canvas で使用できるようにすることです。
referrerpolicy
属性はリファラーポリシー属性です。その目的は、画像をフェッチする際に使用される リファラーポリシーを設定することです。[REFERRERPOLICY]
decoding 属性は、この画像をデコードするための優先方法を示します。この属性が存在する場合、画像デコードヒントでなければなりません。この属性の 欠落値のデフォルト および 無効値のデフォルト はどちらも 自動状態です。
HTMLImageElement/fetchPriority
fetchpriority 属性はフェッチ優先属性です。その目的は、画像をフェッチする際に使用される優先度を設定することです。
loading 属性は遅延読み込み属性です。その目的は、ビューポートの外にある画像を読み込むポリシーを示すことです。
loading 属性の状態が 早期状態に変更されたとき、ユーザーエージェントは次のステップを実行する必要があります:
resumptionSteps を img 要素の遅延読み込み再開ステップに設定します。
もし resumptionSteps が null であれば、終了します。
img の遅延読み込み再開ステップを
null に設定します。
resumptionSteps を実行します。
< img src = "1.jpeg" alt = "1" >
< img src = "2.jpeg" loading = eager alt = "2" >
< img src = "3.jpeg" loading = lazy alt = "3" >
< div id = very-large ></ div > <!-- この div の後のすべての要素はビューポートの下にあります -->
< img src = "4.jpeg" alt = "4" >
< img src = "5.jpeg" loading = lazy alt = "5" >
上記の例では、画像は次のように読み込まれます:
1.jpeg, 2.jpeg, 4.jpegこれらの画像は早期に読み込まれ、ウィンドウの load イベントを遅延させます。
3.jpegこの画像はビューポート内にあるため、レイアウトが判明したときに読み込まれますが、ウィンドウの load イベントを遅延させません。
5.jpegこの画像はビューポートにスクロールされた後にのみ読み込まれ、ウィンドウの load イベントを遅延させません。
開発者は、width および height
属性を使用して遅延読み込みされた画像の好ましいアスペクト比を指定することを推奨します。これは、CSS が画像の width および height
プロパティを設定していても、画像の読み込み後にページレイアウトが移動するのを防ぐためです。
img の insertedNode
に対するHTML
要素挿入ステップは次の通りです:
img の removedNode および
oldParent に対するHTML 要素削除ステップは次の通りです:
img
要素はレイアウトツールとして使用してはなりません。特に、img
要素を透明な画像の表示に使用してはなりません。これらの画像は意味を伝えることがほとんどなく、文書に有用なものを追加することもめったにありません。
img 要素が表す内容は、src 属性および alt 属性によって異なります。
src 属性が設定され、かつ alt 属性が空の文字列に設定されている場合画像は装飾的またはコンテンツの補足的なものであり、文書内の他の情報と冗長である可能性があります。
画像が利用可能であり、ユーザーエージェントがその画像を表示するように設定されている場合、要素はその画像データを表します。
それ以外の場合、要素は何も表しません。レンダリングから完全に省略される場合があります。ユーザーエージェントは、画像が存在するがレンダリングから省略されたことをユーザーに通知する場合があります。
src 属性が設定され、かつ alt 属性が空でない値に設定されている場合画像はコンテンツの重要な部分であり、alt
属性はその画像のテキスト等価物または代替物を提供します。
画像が利用可能であり、ユーザーエージェントがその画像を表示するように設定されている場合、要素はその画像データを表します。
それ以外の場合、要素は alt 属性で指定されたテキストを表します。ユーザーエージェントは、画像が存在するがレンダリングから省略されたことをユーザーに通知する場合があります。
src 属性が設定され、alt 属性が設定されていない場合画像はコンテンツの重要な部分である可能性があり、画像のテキスト等価物が利用できない状態です。
適合文書において、alt
属性が欠如していることは、画像がコンテンツの重要な部分であることを示していますが、画像が生成されたときにその画像のテキストによる代替が利用できなかったことを意味します。
画像が利用可能であり、ユーザーエージェントがその画像を表示するように設定されている場合、要素はその画像データを表します。
画像が空の文字列を持つ src
属性を持っている場合、要素は何も表しません。
それ以外の場合、ユーザーエージェントは画像がレンダリングされていないことを示す何らかの指標を表示すべきです。また、ユーザーの要求に応じて、設定されている場合、またはナビゲーションに応じてコンテキスト情報を提供する必要がある場合、次のようにキャプション情報を提供する場合があります:
画像に空でない値を持つ title
属性がある場合、その属性の値を返します。
画像が figure
要素の子孫であり、その要素が子の figcaption
要素を持っており、figcaption
要素およびその子孫を無視しても figure 要素にフローコンテンツの子孫が他にない場合、最初の figcaption
要素の内容を返します。
何も返しません。(キャプション情報はありません。)
src 属性が設定されておらず、かつ alt
属性が空の文字列に設定されているか、またはまったく設定されていない場合要素は何も表しません。
alt 属性は助言情報を表しません。ユーザーエージェントは alt 属性の内容を title 属性の内容と同じように表示してはなりません。
ユーザーエージェントは、常にユーザーに画像を表示するオプションや、画像の表示を防ぐオプションを提供することができます。ユーザーが画像を見ることができない場合(視覚障害がある場合やグラフィック機能のないテキスト端末を使用している場合など)、ユーザーエージェントはユーザーが画像を活用できるように支援するためのヒューリスティックを適用することもできます。たとえば、画像内のテキストを光学文字認識 (OCR) することなどが考えられます。
ユーザーエージェントは alt
属性が欠落している場合の修復を推奨しますが、著者はそのような動作に依存してはなりません。画像の代替として機能するテキストを提供するための要件については、以下で詳しく説明します。
img
要素の内容は、レンダリングの目的では無視されます。
usemap
属性が存在する場合、画像に関連するイメージマップがあることを示すことができます。
ismap 属性は、a 要素の子孫であり、href
属性を持つ要素に使用された場合、その要素がサーバーサイドイメージマップへのアクセスを提供することを示します。これにより、対応する a 要素でのイベントの処理方法に影響を与えます。
ismap 属性はブール属性です。この属性は、祖先に a 要素があり、href
属性を持っていない要素には指定してはなりません。
usemap および
ismap 属性は、source 要素と、media 属性を指定した picture
要素と一緒に使用されると、混乱を招く動作を引き起こす可能性があります。
すべての現行エンジンでサポートされています。
すべての現行エンジンでサポートされています。
すべての現行エンジンでサポートされています。
alt、src、srcset、およびsizes
IDL属性は、それぞれの同名のコンテンツ属性を反映しなければなりません。
すべての現行エンジンでサポートされています。
crossOrigin
IDL属性は、crossoriginコンテンツ属性を反映し、既知の値にのみ限定されます。
すべての現行エンジンでサポートされています。
useMap
IDL属性は、usemapコンテンツ属性を反映しなければなりません。
すべての現行エンジンでサポートされています。
isMap IDL属性は、ismapコンテンツ属性を反映しなければなりません。
HTMLImageElement/referrerPolicy
すべての現行エンジンでサポートされています。
referrerPolicy IDL属性は、referrerpolicyコンテンツ属性を反映しなければなりません。また、既知の値に限定されます。
すべての現行エンジンでサポートされています。
decoding
IDL属性は、decodingコンテンツ属性を反映し、既知の値に限定されます。
すべての現行エンジンでサポートされています。
loading
IDL属性は、loadingコンテンツ属性を反映し、既知の値に限定されます。
fetchPriority IDL属性は、fetchpriorityコンテンツ属性を反映し、既知の値に限定されます。
image.width [ = value ]
すべての現行エンジンでサポートされています。
image.height [ = value ]
すべての現行エンジンでサポートされています。
これらの属性は、画像の実際のレンダリング寸法を返すか、寸法が不明な場合は0を返します。
それらを設定することにより、対応するコンテンツ属性を変更することができます。
image.naturalWidth
すべての現行エンジンでサポートされています。
image.naturalHeight
HTMLImageElement/naturalHeight
すべての現行エンジンでサポートされています。
これらの属性は、画像の自然な寸法を返すか、寸法が不明な場合は0を返します。
image.complete
すべての現行エンジンでサポートされています。
画像が完全にダウンロードされた場合、または画像が指定されていない場合はtrueを返し、それ以外の場合はfalseを返します。
image.currentSrc
すべての現行エンジンでサポートされています。
画像の絶対URLを返します。
image.decode()
すべての現行エンジンでサポートされています。
このメソッドは、ユーザーエージェントに画像を並行してデコードさせ、デコードが完了すると解決されるpromiseを返します。
画像をデコードできない場合、promiseは"EncodingError" DOMExceptionで拒否されます。
image = new Image([ width [, height ] ])
すべての現行エンジンでサポートされています。
IDL属性widthおよびheightは、画像がレンダリングされている場合は、その画像のレンダリングされた幅と高さをCSSピクセル単位で返さなければなりません。また、画像が密度補正された自然な幅と高さを持ち、利用可能であるが、レンダリングされていない場合は、その幅と高さをCSSピクセル単位で返さなければなりません。そうでない場合、画像が利用可能でないか、密度補正された自然な幅と高さを持っていない場合は、0を返します。[CSS]
設定時には、それらは同じ名前の対応するコンテンツ属性を反映しているかのように動作しなければなりません。
IDL属性naturalWidthおよびnaturalHeightは、画像が密度補正された自然な幅と高さを持ち、利用可能である場合、その幅と高さをCSSピクセル単位で返さなければなりません。そうでない場合は、0を返します。[CSS]
画像の密度補正された自然な幅と高さは、そのメタデータに指定された向きを考慮しているため、naturalWidthおよびnaturalHeightは、'image-orientation'プロパティの値に関係なく、画像を正しく向けるために必要な回転を適用した後の寸法を反映します。
IDL属性completeのゲッターステップは以下の通りです:
次のいずれかが真である場合:
src属性とsrcset属性の両方が省略されている。
srcset属性が省略され、src属性の値が空文字列である。img要素の現在のリクエストの状態が完全に利用可能であり、その保留中のリクエストがnullである。img要素の現在のリクエストの状態が破損している場合、かつ保留中のリクエストがnullである。この場合、trueを返します。
それ以外の場合、falseを返します。
IDL属性currentSrcは、img要素の現在のリクエストの現在のURLを返さなければなりません。
IDLメソッドdecode()は、呼び出されたとき、次のステップを実行しなければなりません:
新しいpromiseを作成します。
マイクロタスクをキューに入れ、次のステップを実行します:
これは、画像データの更新が同じくマイクロタスク内で行われるためです。したがって、次のようなコードを適切に処理するには、
img. src = "stars.jpg" ;
img. decode();
stars.jpgを正しくデコードするには、処理を1つのマイクロタスクだけ遅らせる必要があります。
次のいずれかが真である場合:
この場合、promiseを"EncodingError"DOMExceptionで拒否します。
それ以外の場合は、並列で、次のいずれかのケースが発生するのを待ち、それに応じた処理を実行します:
img要素のノードドキュメントが完全にアクティブでなくなる。img要素の現在のリクエストが変更されるか変形する。img要素の現在のリクエストの状態が破損している。この場合、promiseを"EncodingError"DOMExceptionで拒否します。
img要素の現在のリクエストの状態が完全に利用可能になる。画像をデコードします。
この画像に対してデコードが不要な場合(例えば、ベクターグラフィックであるため)、promiseをundefinedで解決します。
デコードが失敗した場合(例:無効な画像データのため)、promiseを"EncodingError"DOMExceptionで拒否します。
デコードプロセスが正常に完了した場合、promiseをundefinedで解決します。
ユーザーエージェントは、少なくとも次のレンダリングの更新ステップが成功するまで、デコードされたメディアデータが利用可能な状態であることを確保する必要があります。これはAPI契約の重要な部分であり、可能な限り破るべきではありません。(通常、これは低メモリの状況でデコードされた画像データを退避する必要がある場合や、画像が大きすぎてこの期間中にデコードされた形式で保持できない場合にのみ違反されます。)
アニメーション画像は、すべてのフレームがロードされた後にのみ完全に利用可能になります。そのため、実装によっては最初のフレームをその時点より前にデコードすることができますが、上記のステップではそうしないで、すべてのフレームが利用可能になるまで待機します。
promiseを返します。
decode()メソッドを使用しない場合、img要素をロードしてから表示するプロセスは次のようになります:
const img = new Image();
img. src = "nebula.jpg" ;
img. onload = () => {
document. body. appendChild( img);
};
img. onerror = () => {
document. body. appendChild( new Text( "Could not load the nebula :(" ));
};
しかし、これは画像をDOMに挿入した後に発生する描画がメインスレッドでの同期デコードを引き起こすため、フレームが大幅に落ちる可能性があります。
これを代わりにdecode()メソッドを使用して次のように書き換えることができます:
const img = new Image();
img. src = "nebula.jpg" ;
img. decode(). then(() => {
document. body. appendChild( img);
}). catch (() => {
document. body. appendChild( new Text( "Could not load the nebula :(" ));
});
この後者の形式は、ユーザーエージェントが画像を並列でデコードし、デコードプロセスが完了してからDOMに挿入する(つまり、描画を引き起こす)ことにより、元の形式で発生するフレーム落ちを回避します。
decode()メソッドは、デコードされた画像データが少なくとも1フレームにわたって利用可能であることを保証しようとするため、requestAnimationFrame()APIと組み合わせることができます。これは、すべてのDOM変更がアニメーションフレームコールバックとしてまとめられることを保証するコーディングスタイルやフレームワークと共に使用できることを意味します:
const container = document. querySelector( "#container" );
const { containerWidth, containerHeight } = computeDesiredSize();
requestAnimationFrame(() => {
container. style. width = containerWidth;
container. style. height = containerHeight;
});
// ...
const img = new Image();
img. src = "supernova.jpg" ;
img. decode(). then(() => {
requestAnimationFrame(() => container. appendChild( img));
});
レガシーファクトリ関数は、HTMLImageElementオブジェクトを作成するために提供されています(createElement()のようなDOMのファクトリメソッドに加えて):Image(width, height)。このレガシーファクトリ関数が呼び出されたとき、次の手順を実行しなければなりません:
documentを、現在のグローバルオブジェクトの関連するDocumentとします。
もしwidthが指定されている場合、"width"を使用してimgに対して属性値を設定します。
もしheightが指定されている場合、"height"を使用してimgに対して属性値を設定します。
imgを返します。
単一の画像には、文脈に応じて適切な代替テキストが異なる場合があります。
以下の各ケースでは、同じ画像が使用されていますが、毎回 alt
テキストが異なります。
この画像はスイスのジュネーブ州にあるカロージュ市の紋章です。
ここでは補足的なアイコンとして使用されています:
< p > 私はカロージュに住んでいました< img src = "carouge.svg" alt = "" > 。</ p >
ここでは町を表すアイコンとして使用されています:
< p > 故郷: < img src = "carouge.svg" alt = "カロージュ" ></ p >
ここでは町に関する文章の一部として使用されています:
< p > カロージュには紋章があります</ p >
< p >< img src = "carouge.svg" alt = "紋章には木の前に座っているライオンが描かれています。" ></ p >
< p > この紋章は町中の装飾として使われています。</ p >
ここでは、画像の代わりに説明文が提供される場合、または画像の代わりに使用される場合に使用されています:
< p > カロージュには紋章があります</ p >
< p >< img src = "carouge.svg" alt = "" ></ p >
< p > 紋章には木の前に座っているライオンが描かれています。 この紋章は町中の装飾として使われています。</ p >
ここではストーリーの一部として使用されています:
< p > 彼女はフォルダを手に取り、一枚の紙が落ちました。</ p >
< p >< img src = "carouge.svg" alt = "盾の形をした紙には、赤い背景、緑の木、舌を出した黄色いライオンが描かれており、その尾はS字型になっています。" ></ p >
< p > 彼女はフォルダを見つめました。S! 彼女がずっと探していた答えは、単にSの文字でした! それをどうして今まで見逃していたのだろう? 全てが繋がりました。ヘクターがライオンの尾について言及した電話、マリアが舌を出したときのこと…</ p >
ここでは、画像が何であるかは発表時には不明であり、代替テキストを提供できず、画像の簡単なキャプションのみが title 属性に提供されています:
< p > 最後に紋章をアップロードしたユーザーがこの画像をアップロードしました:</ p >
< p >< img src = "last-uploaded-coat-of-arms.cgi" title = "ユーザーがアップロードした紋章。" ></ p >
理想的には、このケースでも実際の代替テキストを提供する方法を見つけることが望ましいです。例えば、前のユーザーに問い合わせるなどして。代替テキストを提供しないことは、画像を表示できない人々(例:視覚障害者、非常に低帯域幅の接続を使用しているユーザー、バイト単位で課金されるユーザー、またはテキストのみのWebブラウザーを使用することを余儀なくされているユーザー)にとって、文書の使用をより困難にします。
同じ画像が異なる文脈で使用され、それぞれに適した異なる代替テキストを持つさらに多くの例を以下に示します。
< article >
< h1 > 私の猫たち</ h1 >
< h2 > フラッフィー</ h2 >
< p > フラッフィーは私のお気に入りです</ p >
< img src = "fluffy.jpg" alt = "彼女は毛糸の玉で遊ぶのが好きです。" >
</ p > 彼女は本当にかわいいです。</ p >
< h2 > マイルズ</ h2 >
< p > 私のもう一匹の猫、マイルズはただ食べて寝るだけです</ p >
</ article >
< article >
< h1 > 写真撮影</ h1 >
< h2 > 室内で動く被写体を撮影する</ h2 >
< p > ここでのコツは、予測することです。被写体がどの速度で、どの距離で通過するかを知ることです</ p >
< img src = "fluffy.jpg" alt = "毛糸の玉を追いかける猫を、この技術でうまく撮影できます。" >
</ h2 > 夜の自然</ h2 >
</ p > これを実現するには、非常に感度の高いフィルム、または強力なフラッシュライトが必要です</ p >
</ article >
< article >
< h1 > 私について</ h1 >
< h2 > 私のペットたち</ h2 >
< p > 私はフラッフィーという名の猫と、マイルズという名の犬を飼っています</ p >
< img src = "fluffy.jpg" alt = "私の猫フラッフィーは、よく一人で遊んでいます。" >
</ p > 私の犬マイルズとは一緒に長い散歩に行くのが好きです</ p >
< h2 > 音楽</ h2 >
</ p > 散歩の後、頭を空っぽにしてバッハを聴くのが好きです</ p >
</ article >
< article >
< h1 > フラッフィーと毛糸</ h1 >
</ p > フラッフィーは毛糸で遊ぶのが好きな猫でした。ジャンプも好きでした</ p >
< aside >< img src = "fluffy.jpg" alt = "" title = "フラッフィー" ></ aside >
</ p > 彼女は朝に遊び、夜に遊びました</ p >
</ article >
このセクションは非規範的です。
HTMLに画像を埋め込むには、画像リソースが1つしかない場合、img要素とそのsrc属性を使用します。
< h2 > 今日の注目記事</ h2 >
< img src = "/uploads/100-marie-lloyd.jpg" alt = "" width = "100" height = "150" >
< p >< b >< a href = "/wiki/Marie_Lloyd" > Marie Lloyd</ a ></ b > (1870–1922) はイギリスの< a href = "/wiki/Music_hall" > ミュージックホール</ a > 歌手で、...
ただし、ユーザーエージェントが選択できる複数の画像リソースを使用したい場合もあります。
異なるユーザーが異なる環境特性を持っているかもしれません:
ユーザーの物理的な画面サイズが異なる場合があります。
携帯電話の画面は対角線で4インチであるのに対し、ノートパソコンの画面は対角線で14インチかもしれません。
これは、画像のレンダリングサイズがビューポートサイズに依存する場合にのみ関連します。
ユーザーの画面のピクセル密度が異なる場合があります。
ある携帯電話の画面は、別の携帯電話の画面と比べて、物理的な画面サイズに関係なく1インチあたりのピクセル数が3倍かもしれません。
ユーザーのズームレベルが異なる場合があり、1人のユーザーが時間と共にズームレベルを変えるかもしれません。
ユーザーは、より詳細に確認するために特定の画像をズームインするかもしれません。
ズームレベルと画面のピクセル密度(前のポイント)は、1つのCSSピクセルあたりの物理的な画面ピクセル数に影響を与えることがあります。この比率は通常、デバイスピクセル比と呼ばれます。
ユーザーの画面の向きが異なるか、1人のユーザーが時間と共に向きを変えるかもしれません。
タブレットは直立して持ったり、90度回転させて画面を「縦向き」または「横向き」にすることができます。
ユーザーのネットワーク速度、ネットワーク遅延および帯域幅コストが異なるか、1人のユーザーが時間と共に変化するかもしれません。
ユーザーは、職場では高速で低遅延、定額制の接続を使用し、自宅では低速で低遅延、定額制の接続を使用し、他の場所では変動速度で高遅延、従量制の接続を使用するかもしれません。
著者は、通常、ビューポートの幅に応じて異なるレンダリングサイズで同じ画像コンテンツを表示したい場合があります。これは通常、ビューポートベースの選択と呼ばれます。
ウェブページは、常にビューポート幅全体にわたるバナーを上部に持つかもしれません。この場合、画像のレンダリングサイズは画面の物理的なサイズに依存します(ブラウザウィンドウが最大化されていると仮定)。
別のウェブページでは、物理的なサイズが小さい画面では1つのカラム、中程度のサイズの画面では2つのカラム、大きな画面では3つのカラムで画像を表示し、各場合に画像のレンダリングサイズを調整してビューポート全体を埋めるようにすることがあります。この場合、1カラムのレイアウトでは、画面が小さいにもかかわらず、画像のレンダリングサイズが2カラムレイアウトよりも大きくなる可能性があります。
著者は、画像のレンダリングサイズに応じて異なる画像コンテンツを表示したい場合があります。これは通常、アートディレクションと呼ばれます。
大きな物理的サイズの画面でウェブページを表示する場合(ブラウザウィンドウが最大化されていると仮定)、著者は画像の重要部分の周囲に関連性の低い部分を含めたいかもしれません。同じウェブページが小さな物理的サイズの画面で表示される場合、著者は画像の重要部分のみを表示したいかもしれません。
著者は、ユーザーエージェントがサポートする画像フォーマットに応じて異なる画像フォーマットを使用して同じ画像コンテンツを表示したい場合があります。これは通常、画像フォーマットベースの選択と呼ばれます。
ウェブページにはJPEG、WebP、JPEG XRの画像フォーマットが含まれており、後者2つはJPEGに比べてより優れた圧縮能力を持っています。異なるユーザーエージェントは異なる画像フォーマットをサポートするため、著者はそれらをサポートするユーザーエージェントに対してより優れたフォーマットを提供し、それをサポートしないユーザーエージェントにはJPEGフォールバックを提供したいと考えています。
上記の状況は相互に排他的ではありません。たとえば、デバイスピクセル比が異なる場合に異なるリソースを組み合わせることと、アートディレクションを組み合わせることは合理的です。
これらの問題をスクリプトを使用して解決することは可能ですが、それにより別の問題が発生します:
一部のユーザーエージェントは、スクリプトが実行される前に、HTMLマークアップで指定された画像を積極的にダウンロードし、ウェブページの読み込みが早く完了するようにします。スクリプトがどの画像をダウンロードするかを変更すると、ユーザーエージェントは2つの別々のダウンロードを開始し、ページの読み込みパフォーマンスが悪化する可能性があります。
著者がHTMLマークアップで画像を指定せず、スクリプトから単一のダウンロードを開始する場合、上記の二重ダウンロードの問題を回避できますが、スクリプトが無効になっているユーザーに対しては画像がまったくダウンロードされず、積極的な画像ダウンロードの最適化も無効になります。
これを踏まえ、この仕様では上記の問題に対処するためにいくつかの機能を宣言的に導入しています。
srcおよびsrcset属性は、img要素に使用され、x記述子を使用して、サイズだけが異なる複数の画像(小さい画像は大きい画像の縮小版です)を提供することができます。
x記述子は、画像のレンダリングサイズがビューポート幅に依存する場合(ビューポートベースの選択)には適していませんが、アートディレクションと一緒に使用することができます。
< h2 > 今日の注目記事</ h2 >
< img src = "/uploads/100-marie-lloyd.jpg"
srcset = "/uploads/150-marie-lloyd.jpg 1.5x, /uploads/200-marie-lloyd.jpg 2x"
alt = "" width = "100" height = "150" >
< p >< b >< a href = "/wiki/Marie_Lloyd" > Marie Lloyd</ a ></ b > (1870–1922) はイギリスの< a href = "/wiki/Music_hall" > ミュージックホール</ a > 歌手で、...
ユーザーエージェントは、ユーザーの画面のピクセル密度、ズームレベル、およびネットワーク状況などの他の要因に応じて、指定されたリソースのいずれかを選択できます。
古いユーザーエージェントとの互換性を確保するために、srcset属性をまだ理解していない場合、URLの1つがimg要素のsrc属性に指定されます。これにより、古いユーザーエージェントでも何かしらの(おそらく低解像度の)画像が表示されます。新しいユーザーエージェントでは、src属性はsrcsetに1x記述子が指定されたかのように、リソース選択に参加します。
画像のレンダリングサイズは幅および高さ属性で指定されており、ユーザーエージェントは画像がダウンロードされる前にそのスペースを確保できます。
srcsetおよびsizes属性はw記述子を使用して、サイズだけが異なる複数の画像(小さい画像は大きい画像の縮小版です)を提供するために使用できます。
この例では、バナー画像がビューポート幅全体を占めています(適切なCSSを使用)。
< h1 >< img sizes = "100vw" srcset = "wolf-400.jpg 400w, wolf-800.jpg 800w, wolf-1600.jpg 1600w"
src = "wolf-400.jpg" alt = "The rad wolf" ></ h1 >
ユーザーエージェントは、指定されたw記述子およびsizes属性に基づいて、各画像の有効なピクセル密度を計算し、ユーザーの画面のピクセル密度、ズームレベル、およびネットワーク状況などの他の要因に応じて、指定されたリソースのいずれかを選択できます。
ユーザーの画面が320CSSピクセル幅の場合、これはwolf-400.jpg 1.25x, wolf-800.jpg 2.5x, wolf-1600.jpg 5xを指定したことに相当します。一方、ユーザーの画面が1200CSSピクセル幅の場合、これはwolf-400.jpg 0.33x, wolf-800.jpg 0.67x, wolf-1600.jpg 1.33xを指定したことに相当します。w記述子およびsizes属性を使用することで、ユーザーエージェントはデバイスのサイズに関係なく、適切な画像ソースをダウンロードできます。
後方互換性を確保するために、URLの1つがimg要素のsrc属性に指定されています。新しいユーザーエージェントでは、src属性は、srcset属性がw記述子を使用している場合に無視されます。
この例では、ビューポート幅に応じて3つのレイアウトが設定されています。狭いレイアウトでは画像が1列(各画像の幅は約100%)、中間レイアウトでは画像が2列(各画像の幅は約50%)、最も広いレイアウトでは画像が3列で、ページの余白もあります(各画像の幅は約33%)。これらのレイアウトは、それぞれ30emおよび50emのビューポート幅で切り替わります。
< img sizes = "(max-width: 30em) 100vw, (max-width: 50em) 50vw, calc(33vw - 100px)"
srcset = "swing-200.jpg 200w, swing-400.jpg 400w, swing-800.jpg 800w, swing-1600.jpg 1600w"
src = "swing-400.jpg" alt = "Kettlebell Swing" >
sizes属性は、30emおよび50emでレイアウトのブレークポイントを設定し、これらのブレークポイント間で画像のサイズを100vw、50vw、またはcalc(33vw - 100px)と宣言します。これらのサイズは、CSSで指定された実際の画像幅と必ずしも一致する必要はありません。
ユーザーエージェントは、sizes属性から幅を選択し、最初に一致する<media-condition>(括弧内の部分)がtrueで評価されるもの、またはすべてがfalseで評価される場合は最後のアイテムcalc(33vw - 100px)を使用します。
たとえば、ビューポート幅が29emの場合、(max-width: 30em)がtrueで評価され100vwが使用されるため、リソース選択の目的で画像サイズは29emです。一方、ビューポート幅が32emの場合、(max-width: 30em)はfalseで評価されますが、(max-width: 50em)はtrueで評価され50vwが使用されるため、リソース選択の目的で画像サイズはビューポート幅の半分である16emになります。わずかに広いビューポートが異なるレイアウトのため、画像が小さくなることに注意してください。
その後、ユーザーエージェントは有効なピクセル密度を計算し、前の例と同様に適切なリソースを選択できます。
この例は前の例と同じですが、画像は遅延ロードされます。この場合、sizes属性はautoキーワードを使用でき、ユーザーエージェントはソースサイズのために幅属性(またはCSSで指定された幅)を使用します。
< img loading = "lazy" width = "200" height = "200" sizes = "auto"
srcset = "swing-200.jpg 200w, swing-400.jpg 400w, swing-800.jpg 800w, swing-1600.jpg 1600w"
src = "swing-400.jpg" alt = "Kettlebell Swing" >
レガシーユーザーエージェントとの互換性を高めるために、autoキーワードをサポートしていない場合、必要に応じてフォールバックサイズを指定できます。
< img loading = "lazy" width = "200" height = "200"
sizes = "auto, (max-width: 30em) 100vw, (max-width: 50em) 50vw, calc(33vw - 100px)"
srcset = "swing-200.jpg 200w, swing-400.jpg 400w, swing-800.jpg 800w, swing-1600.jpg 1600w"
src = "swing-400.jpg" alt = "Kettlebell Swing" >
picture要素およびsource要素は、media属性と組み合わせて、画像コンテンツを変更するために使用できます(例えば、小さい画像は大きい画像のトリミング版である可能性があります)。
< picture >
< source media = "(min-width: 45em)" srcset = "large.jpg" >
< source media = "(min-width: 32em)" srcset = "med.jpg" >
< img src = "small.jpg" alt = "The wolf runs through the snow." >
</ picture >
ユーザーエージェントは、source要素のmedia属性のメディアクエリが一致する最初の要素を選択し、その後、そのsrcset属性から適切なURLを選択します。
選択されたリソースに応じて、画像のレンダリングサイズが変化します。CSSを使用して、ユーザーエージェントが画像をダウンロードする前に使用できる寸法を指定できます。
img { width : 300 px ; height : 300 px }
@media ( min-width: 32em) { img { width: 500px; height:300px } }
@media (min-width: 45em) { img { width: 700px; height:400px } }
この例はアートディレクションとデバイスピクセル比に基づく選択を組み合わせたものです。ビューポートの半分を占めるバナーが、ワイドスクリーン用とナロースクリーン用の2つのバージョンで提供されます。
< h1 >
< picture >
< source media = "(max-width: 500px)" srcset = "banner-phone.jpeg, banner-phone-HD.jpeg 2x" >
< img src = "banner.jpeg" srcset = "banner-HD.jpeg 2x" alt = "朝食コンボ" >
</ picture >
</ h1 >
type属性はsource要素に使用され、異なるフォーマットの複数の画像を提供するために使用できます。
< h2 > 今日の注目記事</ h2 >
< picture >
< source srcset = "/uploads/100-marie-lloyd.webp" type = "image/webp" >
< source srcset = "/uploads/100-marie-lloyd.jxr" type = "image/vnd.ms-photo" >
< img src = "/uploads/100-marie-lloyd.jpg" alt = "" width = "100" height = "150" >
</ picture >
< p >< b >< a href = "/wiki/Marie_Lloyd" > Marie Lloyd</ a ></ b > (1870–1922) はイギリスの< a href = "/wiki/Music_hall" > ミュージックホール</ a > 歌手で、...
この例では、ユーザーエージェントは、サポートされているMIMEタイプを持つtype属性を持つ最初のソースを選択します。ユーザーエージェントがWebP画像をサポートしている場合、最初のsource要素が選択されます。そうでなくても、ユーザーエージェントがJPEG
XR画像をサポートしている場合、2番目のsource要素が選択されます。それらのフォーマットのいずれもサポートされていない場合は、img要素が選択されます。
このセクションは規範的ではありません。
CSSとメディアクエリを使用して、ユーザーの環境に動的に適応するグラフィカルなページレイアウトを構築できます。特に、異なるビューポートの寸法やピクセル密度に対応するためです。しかし、コンテンツに関しては、CSSは助けになりません。代わりに、img要素のsrcset属性とpicture要素を使用します。このセクションでは、これらの機能の使用方法を示すサンプルケースを説明します。
たとえば、幅が600CSSピクセルを超える広い画面では、a-rectangle.pngという名前の300×150の画像を使用し、600CSSピクセル以下の小さな画面では、a-square.pngという名前の100×100の小さい画像を使用する場合、このようなマークアップになります:
< figure >
< picture >
< source srcset = "a-square.png" media = "(max-width: 600px)" >
< img src = "a-rectangle.png" alt = "バーニー・フランクがスーツと眼鏡を着用しています。" >
</ picture >
< figcaption > バーニー・フランク、2011年</ figcaption >
</ figure >
alt属性に何を入れるべきかについては、画像の代替として機能するテキストを提供するための要件のセクションを参照してください。
この問題は、画像の読み込み時にユーザーエージェントが画像の寸法を必ずしも知っているわけではないことです。ページの読み込み中にレイアウトが何度も再フローされるのを防ぐために、CSSとCSSメディアクエリを使用して寸法を提供できます:
< style >
# a { width : 300 px ; height : 150 px ; }
@ media ( max-width : 600px ) { # a { width : 100 px ; height : 100 px ; } }
</ style >
< figure >
< picture >
< source srcset = "a-square.png" media = "(max-width: 600px)" >
< img src = "a-rectangle.png" alt = "バーニー・フランクがスーツと眼鏡を着用しています。" id = "a" >
</ picture >
< figcaption > バーニー・フランク、2011年</ figcaption >
</ figure >
あるいは、widthおよびheight属性を使用して、レガシーユーザーエージェントに対して幅と高さを提供し、CSSを使用してpictureをサポートするユーザーエージェントに対応することもできます:
< style media = "(max-width: 600px)" >
# a { width : 100 px ; height : 100 px ; }
</ style >
< figure >
< picture >
< source srcset = "a-square.png" media = "(max-width: 600px)" >
< img src = "a-rectangle.png" width = "300" height = "150" alt = "バーニー・フランクがスーツと眼鏡を着用しています。" id = "a" >
</ picture >
</ figcaption > バーニー・フランク、2011年</ figcaption >
</ figure >
img要素は、src属性とともに使用され、picture要素をサポートしないレガシーユーザーエージェントに対して使用する画像のURLを指定します。これにより、src属性にどの画像を提供するかという問題が生じます。
著者がレガシーユーザーエージェントで最大の画像を望む場合、マークアップは次のようになります:
< picture >
< source srcset = "pear-mobile.jpeg" media = "(max-width: 720px)" >
< source srcset = "pear-tablet.jpeg" media = "(max-width: 1280px)" >
< img src = "pear-desktop.jpeg" alt = "梨はジューシーです。" >
</ picture >
しかし、レガシーのモバイルユーザーエージェントがより重要な場合は、すべての画像をsource要素にリストし、src属性を完全に無効にすることができます。
< picture >
< source srcset = "pear-mobile.jpeg" media = "(max-width: 720px)" >
< source srcset = "pear-tablet.jpeg" media = "(max-width: 1280px)" >
< source srcset = "pear-desktop.jpeg" >
< img src = "pear-mobile.jpeg" alt = "梨はジューシーです。" >
</ picture >
この時点では、src属性はpictureをサポートするユーザーエージェントによって完全に無視されているため、src属性は、最大でも最小でもない画像にデフォルト設定できます:
< picture >
< source srcset = "pear-mobile.jpeg" media = "(max-width: 720px)" >
< source srcset = "pear-tablet.jpeg" media = "(max-width: 1280px)" >
< source srcset = "pear-desktop.jpeg" >
< img src = "pear-tablet.jpeg" alt = "梨はジューシーです。" >
</ picture >
上記では、max-widthメディア機能を使用して、画像が対象とする最大の(ビューポート)寸法を指定していますが、代わりにmin-widthを使用することも可能です。
< picture >
< source srcset = "pear-desktop.jpeg" media = "(min-width: 1281px)" >
< source srcset = "pear-tablet.jpeg" media = "(min-width: 721px)" >
< img src = "pear-mobile.jpeg" alt = "梨はジューシーです。" >
</ picture >
source、
img、
link
要素に共通の属性
srcset 属性とは、このセクションで定義されている要件を持つ属性のことです。
存在する場合、その値は1つ以上の 画像候補文字列で構成され、 それぞれはU+002Cコンマ文字(,)で次のものと区切られていなければなりません。 画像候補文字列に記述子がなく、URLの後に ASCII空白文字がない場合、 次の 画像候補文字列は 1つ以上の ASCII空白文字で始まらなければなりません。
画像候補文字列は、以下のコンポーネントで構成され、リストの下に説明されている追加の制限があります。
0個以上の ASCII空白文字。
有効な非空URLで、U+002Cコンマ文字(,)で始まらず、終わらないもので、非対話型でオプションでアニメーション可能な、ページングもスクリプトもされていない画像リソースを参照します。
0個以上の ASCII空白文字。
以下のいずれかを0個または1個含みます:
0個以上の ASCII空白文字。
同じ要素に対して、別の画像候補文字列の幅の記述子の値と同じ幅の記述子の値を持つ画像候補文字列が存在してはなりません。
同じ要素に対して、別の画像候補文字列のピクセル密度記述子の値と同じピクセル密度記述子の値を持つ画像候補文字列が存在してはなりません。この要件の目的では、記述子を持たない画像候補文字列は、1xの記述子を持つ画像候補文字列と同等と見なされます。
要素に対して、幅の記述子が指定されている場合、その要素の他のすべての画像候補文字列も幅の記述子を指定していなければなりません。
画像候補文字列の幅の記述子に指定された幅は、その画像候補文字列のURLによって提供されるリソースの自然な幅と一致していなければなりません(自然な幅が存在する場合)。
要素にsizes属性が存在する場合、その要素のすべての画像候補文字列は幅の記述子を指定していなければなりません。
サイズ属性とは、このセクションで定義されている要件を持つ属性のことです。
存在する場合、その値は 有効なソースサイズリストでなければなりません。
有効なソースサイズリストとは、次の文法に一致する文字列のことです: [CSSVALUES] [MQ]
< source-size-list > = < source-size > #? , < source-size-value >
< source-size > = < media-condition > < source-size-value > | auto
< source-size-value > = < length > | auto
<source-size-value>が<長さ>の場合、その値は負であってはならず、数学関数以外のCSS関数を使用してはなりません。
キーワードautoは、サイズ属性を解析で計算された幅を示します。存在する場合、それは最初のエントリでなければならず、<source-size-list>全体の値が"auto"(ASCII大文字小文字を区別しない)であるか、"auto,"(ASCII大文字小文字を区別しない)で始まらなければなりません。
もし、img要素が画像のロードを開始し、画像データを更新または環境の変化に対応アルゴリズムによってロードが開始されている場合は、自動サイズを許可し、レンダリングされている場合、autoが具体的なオブジェクトサイズの幅となります。そうでない場合、autoの値は無視され、代わりに次のソースサイズが使用されます。
autoキーワードは、次の条件が満たされている場合、サイズ属性のソース要素およびサイズ属性のimg要素で指定することができます。そうでない場合、autoを指定してはなりません。
さらに、幅および高さ属性やCSSを使用して寸法を指定することが強く推奨されます。寸法が指定されていない場合、sizes="auto"はレンダリングセクションでcontain-intrinsic-size: 300px 150pxを意味するため、画像はおそらく300x150の寸法でレンダリングされることになります。
<source-size-value>は画像の意図したレイアウト幅を示します。著者は、<メディア条件>を使用して、異なる環境に対して異なる幅を指定できます。
パーセンテージは<source-size-value>では許可されていません。これは、それが何に対して相対的であるかについての混乱を避けるためです。'vw'ユニットは、ビューポート幅に対して相対的なサイズに使用できます。
img要素には、現在のリクエストと保留中のリクエストがあります。現在のリクエストは最初、新しい画像リクエストに設定されます。保留中のリクエストは最初、nullに設定されます。
画像リクエストには、状態、現在のURL、および画像データがあります。
画像リクエストの画像データは、デコードされた画像データです。
画像リクエストの状態が部分的に利用可能または完全に利用可能である場合、画像リクエストは利用可能とされます。
img要素の現在のリクエストの状態が完全に利用可能であり、ユーザーエージェントがメディアデータをエラーなくデコードできる場合、img要素は完全にデコード可能とされます。
img要素の現在のリクエストが利用可能である場合、img要素は、画像の密度補正済み自然幅(あれば)を持つ描画ソースを提供し、高さは画像の密度補正済み自然高さ(あれば)となり、外観は画像の自然な外観となります。
img要素は、srcset属性が指定されているか、親要素がpicture要素である場合に、srcsetまたはpictureを使用するとされています。
すべてのimg要素には、最後に選択されたソースがあり、最初はnullに設定されている必要があります。
すべての画像リクエストには、現在のピクセル密度があり、最初は1に設定されている必要があります。
すべての画像リクエストには、優先される密度補正済み寸法があり、それは幅と高さを含む構造体かnullである必要があります。最初はnullに設定されている必要があります。
img要素imgの密度補正済み自然幅と高さを決定するために:
dimをimgの現在のリクエストの優先される密度補正済み寸法に設定します。
優先される密度補正済み寸法は、画像内のメタ情報に基づいて画像をプレゼンテーションに準備するアルゴリズムで設定されます。
dimがnullの場合、dimをimgの自然な寸法に設定します。
dimを返します。
例えば、現在のピクセル密度が3.125の場合、それは1インチあたり300デバイスピクセルがあることを意味し、画像データが300x600の場合、密度補正済み自然幅と高さは96 CSSピクセル x 192 CSSピクセルとなります。
すべてのimgおよびlink要素は、ソースセットと関連付けられています。
ソースセットは、0個以上の画像ソースとソースサイズからなる順序付けられたセットです。
画像ソースは、URLであり、オプションでピクセル密度記述子または幅記述子を持ちます。
ソースサイズは、<source-size-value>です。ソースサイズがビューポートに対して相対的な単位を持つ場合、それはimg要素のノードドキュメントのビューポートに対して解釈されなければなりません。他の単位はメディアクエリでの解釈と同じでなければなりません。[MQ]
構文解析エラーは、このセクションのアルゴリズムにおける入力と要件の非致命的な不一致を示します。ユーザーエージェントは、構文解析エラーを何らかの形で公開することが推奨されます。
画像が正常にフェッチされたかどうか(例: レスポンスステータスがOKステータスであったかどうか)は、画像のタイプやそれが有効な画像であるかどうかを判断する際には無視されなければなりません。
これにより、サーバーがエラー応答を返した画像でも、それが表示されることが可能になります。
ユーザーエージェントは、画像のタイプを判断するために、画像の関連するコンテンツタイプヘッダーが公式のタイプを示すように、画像のスニッフィングルールを適用する必要があります。これらのルールが適用されない場合は、画像のタイプは画像の関連するコンテンツタイプヘッダーで示されるタイプでなければなりません。
ユーザーエージェントは、img要素で非画像リソース(例: ドキュメント要素がHTML要素であるXMLファイル)をサポートしてはなりません。ユーザーエージェントは、画像リソースに埋め込まれた実行可能コード(例:
スクリプト)を実行してはなりません。ユーザーエージェントは、マルチページリソース(例:
PDFファイル)の最初のページのみを表示しなければなりません。ユーザーエージェントは、リソースがインタラクティブに動作することを許可してはなりませんが、リソース内のアニメーションは尊重する必要があります。
この仕様は、どの画像タイプがサポートされるべきかを規定していません。
デフォルトでは、画像はすぐに取得されます。ユーザーエージェントは、代わりにオンデマンドで取得するオプションをユーザーに提供することができます。(たとえば、帯域幅が制限されているユーザーがオンデマンドオプションを使用することがあります。)
画像をすぐに取得する場合、ユーザーエージェントは、img要素が作成されたとき、または関連する変更が発生したときに、必要に応じてアニメーションを再起動するフラグを設定し、その要素の画像データを同期的に更新しなければなりません。
オンデマンドで画像を取得する場合、ユーザーエージェントは、img要素の画像データが必要なときに(つまり、オンデマンドで)画像データを更新しなければなりませんが、img要素の現在のリクエストの状態が利用不可の場合に限ります。img要素が関連する変更を受けた場合、ユーザーエージェントが画像をオンデマンドでのみ取得する場合、img要素の現在のリクエストの状態は利用不可に戻る必要があります。
img要素に対する関連する変異は以下の通りです。
要素のsrc属性が前回と同じ値に設定された場合。この場合、画像データの更新アルゴリズムのためにアニメーションを再起動するフラグを設定しなければなりません。
要素のcrossorigin属性の状態が変更された場合。
要素のreferrerpolicy属性の状態が変更された場合。
imgまたはsourceのHTML要素の挿入手順またはHTML要素の削除手順が関連する変異とみなされる場合。
要素の親がpicture要素であり、前の兄弟要素であるsource要素のsrcset、sizes、media、type、widthまたはheight属性が設定、変更、または削除された場合。
要素の採用手順が実行された場合。
要素が自動サイズを許可する場合:要素がレンダリングされているか、またはその具体的なオブジェクトサイズの幅が変わる場合。これは画像データを更新するアルゴリズムのためにイベントを省略するかもしれないフラグを設定しなければなりません。
各Documentオブジェクトには、利用可能な画像のリストが必要です。このリスト内の各画像は、絶対URL、CORS設定属性モード、およびモードがNo CORSでない場合はオリジンを含むタプルで識別されます。また、各画像には上位レイヤーキャッシュを無視するフラグが付いています。ユーザーエージェントは、いつでも1つのDocumentオブジェクトの利用可能な画像のリストのエントリを別のオブジェクトにコピーできます(例: Documentが作成されたときに、他のDocument内で読み込まれたすべての画像を追加できます)。ただし、この方法でコピーされたエントリのキーを変更してはならず、コピーされたエントリの上位レイヤーキャッシュを無視フラグは解除される必要があります。ユーザーエージェントは、メモリを節約するためなどに、これらのリストから画像をいつでも削除できます。ユーザーエージェントは、リソースの上位レイヤーキャッシュのセマンティクスに応じて、利用可能な画像のリストのエントリを適切に削除する必要があります(例: HTTP
`Cache-Control`レスポンスヘッダー)。上位レイヤーキャッシュを無視フラグが解除された場合に限ります。
利用可能な画像のリストは、src属性を以前にロードされたURLに変更する際に同期的な切り替えを可能にし、同じドキュメント内でキャッシュを許可しない場合でも画像の再ダウンロードを避けるために意図されています。これは、前の画像がまだロード中である間に同じ画像を再ダウンロードすることを避けるためには使用されません。
ユーザーエージェントは、利用可能な画像のリストとは別に画像データを保存することもできます。
例えば、リソースがHTTPレスポンスヘッダー`Cache-Control: must-revalidate`を持ち、その上位レイヤーキャッシュを無視するフラグが解除されている場合、ユーザーエージェントはそれを利用可能な画像のリストから削除しますが、画像データを別途保存し、サーバーが`304 Not Modified`ステータスで応答した場合にそれを使用することができます。
画像データは通常、ファイルサイズを削減するためにエンコードされています。そのため、ユーザーエージェントが画像を画面に表示するためには、そのデータをデコードする必要があります。デコードとは、画像のメディアデータをビットマップ形式に変換し、画面に表示できるようにするプロセスです。このプロセスは、コンテンツの表示に関わる他のプロセスに比べて遅いことがあります。そのため、ユーザーエージェントは最適なユーザーエクスペリエンスを提供するために、デコードを実行するタイミングを選択できます。
画像のデコードは、それが完了するまで他のコンテンツの表示を妨げる場合、同期的であると言われます。通常、これにより、画像と他のコンテンツが同時に原子的に表示される効果があります。ただし、この表示は、デコードにかかる時間の分だけ遅れます。
画像のデコードが他のコンテンツの表示を妨げない場合、それは非同期的であると言われます。これにより、非画像コンテンツがより早く表示される効果があります。ただし、デコードが完了するまで画像コンテンツは画面に表示されません。デコードが完了すると、画面は画像で更新されます。
同期モードと非同期モードのどちらでも、最終的なコンテンツは同じ時間が経過した後に画面に表示されます。主な違いは、ユーザーエージェントが最終的なコンテンツを表示する前に非画像コンテンツを先行して表示するかどうかです。
ユーザーエージェントが同期デコードを行うか非同期デコードを行うかを決定する際の補助として、decoding属性をimg要素に設定することができます。decoding属性の可能な値は、以下の画像デコードのヒントキーワードです。
| キーワード | 状態 | 説明 |
|---|---|---|
sync
| 同期 | この画像を他のコンテンツと原子的に表示するために、同期的にデコードすることを示します。 |
async
| 非同期 | 他のコンテンツの表示を遅らせないために、この画像を非同期的にデコードすることを示します。 |
auto
| 自動 | デコードモードに関する特別な指定がないことを示します(デフォルト)。 |
画像をデコードする際、ユーザーエージェントはdecoding属性の状態で示された優先度を尊重するべきです。状態が自動の場合、ユーザーエージェントは任意のデコード動作を選択できます。
decode()メソッドを使用して、デコード動作を制御することも可能です。decode()メソッドは、コンテンツを画面に表示するプロセスとは独立してデコードを実行するため、decoding属性の影響を受けません。
このアルゴリズムは並行して実行されているステップからは呼び出せません。ユーザーエージェントが並行して実行されているステップからこのアルゴリズムを呼び出す必要がある場合、タスクをキューに入れる必要があります。
ユーザーエージェントがimg要素の画像データを更新する場合、オプションでアニメーションの再起動フラグが設定されている場合や、オプションでイベントの省略フラグが設定されている場合は、以下のステップを実行する必要があります。
要素のノードドキュメントが完全にアクティブでない場合、次のようにします:
このアルゴリズムを並行して実行し続けます。
このインスタンスの後にこのimg要素に対するこのアルゴリズムの別のインスタンスが開始された場合(たとえそれが中止され、もはや実行されていなくても)、戻ります。
このアルゴリズムを続行するためにマイクロタスクをキューに入れます。
ユーザーエージェントが画像をサポートできないか、画像のサポートが無効になっている場合は、画像リクエストを中止し、現在のリクエストと保留中のリクエストの状態を利用不可に設定し、保留中のリクエストをnullに設定して戻ります。
selected sourceをnullに、selected pixel densityを未定義に設定します。
要素がsrcsetまたはpictureを使用しておらず、src属性が指定されていて、その値が空文字列でない場合、selected
sourceを要素のsrc属性の値に設定し、selected
pixel densityを1.0に設定します。
要素の最後に選択されたソースをselected sourceに設定します。
selected sourceがnullでない場合、次のステップを実行します:
urlStringを、要素のノードドキュメントに相対的にselected sourceをURLのエンコーディング、パース、およびシリアライズした結果として設定します。
urlStringが失敗した場合、この内側のステップセットを中止します。
keyを、urlString、要素のimg要素のcrossorigin属性のモード、およびそのモードがNo
CORSでない場合、要素のノードドキュメントのオリジンからなるタプルに設定します。
利用可能な画像のリストにkeyのエントリが含まれている場合、次のようにします:
そのエントリの上位レイヤーキャッシュを無視するフラグを設定します。
保留中のリクエストをnullに設定します。
現在のリクエストを、新しい画像リクエストに設定し、その画像データをエントリのデータにし、その状態を完全に利用可能に設定します。
imgに対して現在のリクエストをプレゼンテーションの準備を行います。
DOM操作タスクソースでimg要素に対して以下のステップを実行するタスクをキューに入れます:
アニメーションの再起動が設定されている場合、アニメーションを再起動します。
イベントを省略が設定されていない場合、またはpreviousURLがurlStringと等しくない場合、loadイベントをimg要素に発火します。
画像データの更新アルゴリズムを中止します。
マイクロタスクをキューに入れます、このアルゴリズムの残りの部分を実行し、アルゴリズムを呼び出したタスクを続行できるようにします。
このimg要素に対するこのアルゴリズムの別のインスタンスが、このインスタンスの後に開始された場合(たとえそれが中止され、もはや実行されていなくても)、戻ります。
例えば、src、srcset、crossorigin属性が連続して設定される場合などに、複数のリクエストを回避するために、最後のインスタンスのみが効果を持ちます。
selected sourceとselected pixel densityを、それぞれ画像ソースを選択する結果のURLとピクセル密度に設定します。
selected sourceがnullである場合、次のようにします:
現在のリクエストの状態を壊れたに設定し、画像リクエストを中止し、保留中のリクエストをnullに設定します。
DOM操作タスクソースでimg要素に対して以下のステップを実行するタスクをキューに入れます:
戻ります。
urlStringを、要素のノードドキュメントに相対的にselected sourceをURLのエンコーディング、パース、およびシリアライズした結果として設定します。
urlStringが失敗した場合、次のようにします:
保留中のリクエストがnullでなく、urlStringがpending requestの現在のURLと同じ場合、戻ります。
urlStringがcurrent requestの現在のURLと同じであり、current requestの状態が部分的に利用可能である場合、pending requestの画像リクエストを中止し、DOM操作タスクソースでimg要素に対して以下のステップを実行するタスクをキューに入れ、アニメーションの再起動が設定されている場合は、アニメーションを再起動します。
保留中のリクエストの画像リクエストを中止します。
current requestの状態が利用不可または壊れたである場合、current requestをimage requestに設定します。それ以外の場合は、pending requestをimage requestに設定します。
requestを、urlString、"image"、および要素のcrossoriginコンテンツ属性の現在の状態を与えて潜在的なCORSリクエストを作成した結果に設定します。
requestのクライアントを、要素のノードドキュメントの関連設定オブジェクトに設定します。
要素がsrcsetまたはpictureを使用している場合、requestのイニシエータを"imageset"に設定します。
requestのリファラーポリシーを、要素のreferrerpolicy属性の現在の状態に設定します。
requestの優先度を、要素のfetchpriority属性の現在の状態に設定します。
delay load eventを、imgの遅延ロード属性がEager状態にある場合、またはimgのためにスクリプトが無効化されている場合はtrueに設定し、それ以外の場合はfalseに設定します。
imgに対して遅延ロード要素ステップを実行するがtrueを返す場合、次のようにします:
imgの遅延ロード再開ステップを、このアルゴリズムの残り部分に設定し、画像を取得ステップから始めます。
img要素に対して遅延ロード要素のインターセクション監視を開始します。
戻ります。
画像を取得: フェッチ requestを行います。このアルゴリズムから戻り、フェッチのプロセス応答の一部として残りのステップを実行します。
この方法で取得されたリソースは、image requestの画像データです。それはCORS-同一オリジンまたはCORS-クロスオリジンのいずれかであり、これは画像が他のAPIとどのように相互作用するか(例:
canvasに使用された場合)に影響します。
delay load eventがtrueの場合、画像のフェッチは、リソースがフェッチされた後にネットワーキングタスクソースによってキューに入れられたタスクが実行されるまで、その要素のノードドキュメントのロードイベントを遅延させなければなりません。
これにより、ユーザーのローカルネットワークの簡単なポートスキャンを実行することが可能になります(特にスクリプティングと組み合わせた場合、ただしスクリプティングは実際にはそのような攻撃を実行するために必要ではありません)。ユーザーエージェントは、この攻撃を緩和するために、上記で説明されているものより厳格なクロスオリジンアクセス制御ポリシーを実装することができますが、残念ながらそのようなポリシーは通常、既存のウェブコンテンツとの互換性がありません。
できるだけ早く、次のリストから適用可能な最初のエントリにジャンプします:
multipart/x-mixed-replaceである場合
画像がフェッチされている間に、ネットワーキングタスクソースによってキューに入れられた次のタスクは、次のステップを実行する必要があります:
image requestが保留中のリクエストであり、少なくとも1つのボディパートが完全にデコードされている場合、現在のリクエストを中止し、保留中のリクエストを現在のリクエストにアップグレードします。
それ以外の場合、image requestが保留中のリクエストであり、ユーザーエージェントがimage requestの画像が致命的に破損していて、画像の寸法を取得できないことを確認できる場合、現在のリクエストを中止し、保留中のリクエストを現在のリクエストにアップグレードし、image requestの状態を壊れたに設定します。
それ以外の場合、image requestが現在のリクエストであり、その状態が利用不可であり、ユーザーエージェントがimage requestの画像の幅と高さを確認できる場合、current requestの状態を部分的に利用可能に設定します。
それ以外の場合、image requestが現在のリクエストであり、その状態が利用不可であり、ユーザーエージェントがimage requestの画像が致命的に破損していて、画像の寸法を取得できないことを確認できる場合、current requestの状態を壊れたに設定します。
画像がフェッチされている間に、ネットワーキングタスクソースによってキューに入れられた次のタスクは画像のプレゼンテーションを更新する必要がありますが、各新しいボディパートが入ってきたときに、ユーザーエージェントが画像の幅と高さを確認できる場合、要素に対して画像リクエストをプレゼンテーションの準備を行い、前の画像を置き換えます。1つのボディパートが完全にデコードされたら、次のステップを実行します:
画像がフェッチされている間に、ネットワーキングタスクソースによってキューに入れられた次のタスクは、次のステップを実行する必要があります:
ユーザーエージェントがimage requestの画像の幅と高さを確認でき、image requestが保留中のリクエストである場合、image requestの状態を部分的に利用可能に設定します。
それ以外の場合、ユーザーエージェントがimage requestの画像の幅と高さを確認でき、image requestが現在のリクエストである場合、image requestを要素に対してプレゼンテーションの準備を行い、image requestの状態を部分的に利用可能に設定します。
それ以外の場合、ユーザーエージェントがimage requestの画像が致命的に破損していて、画像の寸法を取得できないことを確認でき、image requestが保留中のリクエストである場合、次のようにします:
それ以外の場合、ユーザーエージェントがimage requestの画像が致命的に破損していて、画像の寸法を取得できないことを確認でき、image requestが現在のリクエストである場合、次のようにします:
画像リクエストを中止します。
イベントを省略が設定されていない場合、またはpreviousURLがurlStringと等しくない場合、errorイベントをimg要素に発火します。
そのタスクと、それに続く各タスク(画像がフェッチされている間にimage requestが現在のリクエストである場合)、および各タスクがネットワーキングタスクソースによってキューに入れられるキューされる場合、適切に画像のプレゼンテーションを更新する必要があります(例: 画像がプログレッシブJPEGである場合、各パケットが画像の解像度を改善できます)。
さらに、リソースがフェッチされた後にネットワーキングタスクソースによってキューに入れられた最後のタスクは、追加で以下のステップを実行する必要があります:
image requestが保留中のリクエストである場合、画像リクエストを中止し、現在のリクエストに対して、保留中のリクエストを現在のリクエストにアップグレードし、プレゼンテーションのためにimage
requestを準備します。img要素に基づいて行います。
image requestを完全に利用可能な状態に設定します。
keyを使用して、利用可能な画像のリストに画像を追加し、上位レイヤーのキャッシングを無視するフラグを設定します。
maybe omit
eventsが設定されていない、またはpreviousURLがurlStringと等しくない場合、イベントを発火します。このイベントはloadという名前で、img要素で発生します。
画像データがサポートされているファイル形式ではない場合、ユーザーエージェントはimage requestの状態を壊れたに設定し、現在のリクエストと保留中のリクエストの画像リクエストを中止し、保留中のリクエストを現在のリクエストにアップグレードし、イベントを省略が設定されていない場合、またはpreviousURLがurlStringと等しくない場合、errorイベントをimg要素に発火します。
ユーザーエージェントが上記のアルゴリズムを要素xに対して実行している間、その要素が接続されているかどうかに関係なく、要素のノードドキュメントから要素xへの強い参照が存在しなければなりません。
画像リクエストを中止するとは、画像リクエストまたはnullのimage requestに対して、以下の手順を実行することを意味します:
image requestがnullの場合、終了します。
存在する場合は、image requestの画像データを忘れます。
image requestに対するフェッチアルゴリズムの実行を中止し、そのアルゴリズムによって生成された保留中のタスクを破棄します。
保留中のリクエストを現在のリクエストにアップグレードするとは、img要素に対して、以下の手順を実行することを意味します:
画像要素imgに対して画像リクエストreqを準備するには、以下の手順を実行します:
exifTagMapを、関連するコーデックで定義されている通りに、reqの画像データから取得したEXIFタグとします。
physicalWidthとphysicalHeightを、関連するコーデックで定義されている通りに、reqの画像データから取得した幅と高さとします。
dimXをexifTagMapのタグ0xA002 (PixelXDimension)の値とします。
dimYをexifTagMapのタグ0xA003 (PixelYDimension)の値とします。
resXをexifTagMapのタグ0x011A (XResolution)の値とします。
resYをexifTagMapのタグ0x011B (YResolution)の値とします。
resUnitをexifTagMapのタグ0x0128 (ResolutionUnit)の値とします。
dimXまたはdimYのいずれかが正の整数でない場合、終了します。
resXまたはresYのいずれかが正の浮動小数点数でない場合、終了します。
resUnitが2 (インチ)に等しくない場合、終了します。
widthFromDensityをphysicalWidthの値に72を掛けたものをresXで割ったものとします。
heightFromDensityをphysicalHeightの値に72を掛けたものをresYで割ったものとします。
widthFromDensityがdimXと等しくない場合、またはheightFromDensityがdimYと等しくない場合、終了します。
reqの画像データがCORSクロスオリジンの場合、imgの自然な寸法をdimXとdimYに設定し、imgのピクセルデータをそれに応じてスケールし、終了します。
reqの優先される密度補正寸法を、幅をdimXに、高さをdimYに設定した構造体に設定します。
reqのimg要素のプレゼンテーションを適切に更新します。
EXIFの解像度はCSSポイント/インチに相当するため、解像度からサイズを計算するための基準は72です。
画像がすでに表示された後にEXIFが到着した場合の扱いはまだ規定されていません。詳細はissue #4929を参照してください。
画像要素elに対してimgを指定して画像ソースを選択するには、以下の手順を実行します:
ソースセットsourceSetに対して画像ソースを選択するには、以下の手順を実行します:
もしsourceSetのエントリーbが、以前のエントリーaと同じピクセル密度記述子を持つ場合、そのエントリーbを削除します。このステップを、sourceSet内のエントリーが以前のエントリーと同じピクセル密度記述子を持たなくなるまで繰り返します。
selectedSourceとその関連するピクセル密度を返します。
文字列default source、文字列srcset、文字列sizes、および要素またはnullimgを指定してソースセットを作成するには、以下の手順を実行します:
source setを空のソースセットとします。
もしsrcsetが空でない文字列であれば、source setを解析した結果に設定します。
もしdefault sourceが空でなく、source setにピクセル密度記述子の値が1である画像ソースや、幅記述子を持つ画像ソースが含まれていない場合、default sourceをsource setに追加します。
source setのソース密度を正規化します。
source setを返します。
特定のimgまたはlink要素elのソースセットを更新するよう求められた場合、ユーザーエージェントは以下の処理を行わなければなりません:
elementsを「el」に設定します。
elが親ノードがpicture要素であるimg要素の場合、elementsの内容をelの親ノードの子要素に置き換え、相対順序を保持します。
imgをelがimg要素である場合はelに、それ以外の場合はnullに設定します。
各childをelements内で次のように処理します:
childがelである場合:
default sourceを空文字列に設定します。
srcsetを空文字列に設定します。
sizesを空文字列に設定します。
それ以外の場合、elがlink要素であり、imagesrcset属性を持っている場合、その属性の値をsrcsetに設定します。
それ以外の場合、elがlink要素であり、imagesizes属性を持っている場合、その属性の値をsizesに設定します。
それ以外の場合、elがlink要素であり、href属性を持っている場合、その属性の値をdefault
sourceに設定します。
elのソースセットを、default source、srcset、sizes、およびimgを与えてソースセットを作成する結果に設定します。
終了します。
elがlink要素である場合、elementsにはelのみが含まれているため、このステップはすぐに実行され、アルゴリズムの残りの部分は実行されません。
childのsrcset属性を解析するを実行し、返されたソースセットをsource setに設定します。
childのsizes属性を解析するをimgに対して実行し、source setのソースサイズを返された値に設定します。
childがwidthまたはheight属性を持っている場合、elの寸法属性ソースをchildに設定します。それ以外の場合は、elの寸法属性ソースをelに設定します。
elのソースセットをsource setに設定します。
終了します。
各img要素は、直前の兄弟source要素およびimg要素自体を考慮し、画像ソースを選択します。他の(無効な)要素、同じpicture要素内の他のimg要素、または該当するimg要素の後続の兄弟source要素は無視されます。
要素からsrcset属性を解析するように要求された場合、要素のsrcset属性の値を次のように解析します:
inputをこのアルゴリズムに渡された値とします。
positionをinput内のポインタとし、初期位置を文字列の先頭に設定します。
candidatesを最初は空のソースセットとします。
分割ループ: コードポイントのシーケンスを収集し、positionを指定してinputからspace-charactersまたはU+002C COMMA文字を収集します。U+002C COMMA文字が収集された場合、それは解析エラーです。
positionがinputの終わりを越えている場合、candidatesを返します。
コードポイントのシーケンスを収集し、positionを指定してinputからspace-characters-2以外のものを収集し、それをurlとします。
descriptorsを新しい空のリストとします。
urlがU+002C (,)で終わる場合:
urlからすべての末尾のU+002C COMMA文字を削除します。これで複数の文字が削除された場合、それは解析エラーです。
それ以外の場合:
ディスクリプタトークナイザ: ASCII空白文字をスキップし、inputとpositionを指定します。
current descriptorを空の文字列とします。
stateをin descriptorに設定します。
cをpositionでの文字とします。このステップでは、"EOF"はinputの終わりを超えた位置を表す特別な文字です。
cの値に応じて次の処理を行います:
current descriptorが空でない場合、それをdescriptorsに追加し、current descriptorを空の文字列に設定します。stateをafter descriptorに設定します。
positionをinput内の次の文字に進めます。current descriptorが空でない場合、それをdescriptorsに追加します。ディスクリプタパーサーのステップにジャンプします。
cをcurrent descriptorに追加します。stateをin parensに設定します。
current descriptorが空でない場合、それをdescriptorsに追加します。ディスクリプタパーサーのステップにジャンプします。
cをcurrent descriptorに追加します。
cの値に応じて次の処理を行います:
cをcurrent descriptorに追加します。stateをin descriptorに設定します。
current descriptorをdescriptorsに追加します。ディスクリプタパーサーのステップにジャンプします。
cをcurrent descriptorに追加します。
cの値に応じて次の処理を行います:
この状態のままにします。
ディスクリプタパーサーのステップにジャンプします。
stateをin descriptorに設定し、positionをinput内の前の文字に戻します。
positionをinput内の次の文字に進めます。このステップを繰り返します。
将来の追加に互換性を持たせるため、このアルゴリズムは複数のディスクリプタや括弧付きのディスクリプタをサポートします。
ディスクリプタパーサー: errorをnoとします。
widthをabsentとします。
densityをabsentとします。
future-compat-hをabsentとします。
descriptors内の各ディスクリプタについて、次のリストから適切なステップを実行します:
ユーザーエージェントがsizes属性をサポートしていない場合、errorをyesとします。
準拠するユーザーエージェントはsizes属性をサポートします。ただし、ユーザーエージェントは通常、機能を段階的に実装して出荷します。
widthとdensityの両方がabsentでない場合、errorをyesとします。
非負整数を解析するためのルールをディスクリプタに適用します。結果が0の場合、errorをyesとします。それ以外の場合、widthをその結果とします。
width、density、future-compat-hのすべてがabsentでない場合、errorをyesとします。
浮動小数点数値を解析するためのルールをディスクリプタに適用します。結果が0未満の場合、errorをyesとします。それ以外の場合、densityをその結果とします。
densityが0の場合、自然な寸法が無限大になります。ユーザーエージェントは、画像がどれだけ大きく表示されるかに制限があると予想されます。
これは解析エラーです。
future-compat-hとdensityの両方がabsentでない場合、errorをyesとします。
非負整数を解析するためのルールをディスクリプタに適用します。結果が0の場合、errorをyesとします。それ以外の場合、future-compat-hをその結果とします。
errorをyesとします。
future-compat-hがabsentでなく、widthがabsentの場合、errorをyesとします。
errorがnoのままであれば、新しい画像ソースをcandidatesに追加します。そのURLがurlであり、幅がabsentでない場合はwidth、ピクセル密度がabsentでない場合はdensityに関連付けられています。それ以外の場合、解析エラーが発生します。
分割ループのステップに戻ります。
要素elementから、img要素またはnullimgを指定してsizes属性を解析するように要求された場合:
unparsed sizes listを、elementのsizes属性の値からコンマ区切りのコンポーネント値リストを解析した結果とします(属性が存在しない場合は空の文字列)。[CSSSYNTAX]
sizeをnullとします。
unparsed sizes list内の各unparsed sizeについて:
unparsed sizeの末尾からすべての連続する<whitespace-token>を削除します。unparsed sizeが空になった場合、それは解析エラーです。続行します。
もしunparsed sizeの最後のコンポーネント値が有効な非負の<source-size-value>である場合、その値をsizeに設定し、unparsed sizeからコンポーネント値を削除します。数学関数以外のCSS関数は無効です。それ以外の場合は解析エラーが発生し、続行します。
もしsizeがautoであり、imgがnullでなく、imgがレンダリングされている場合、そしてimgが自動サイズを許可する場合、sizeをimgの具体的なオブジェクトサイズの幅(CSSピクセル)に設定します。
もしsizeがまだautoである場合、それは無視されます。
unparsed sizeの末尾からすべての連続する<whitespace-token>を削除します。unparsed sizeが空になった場合:
残りのコンポーネント値をunparsed sizeで<メディア条件>として解析します。正しく解析されなかった場合、または正しく解析されたが<メディア条件>がfalseに評価された場合、続行します。[MQ]
もしsizeがautoでない場合、そのsizeを返します。それ以外の場合は続行します。
100vwを返します。
裸の<source-size-value>(<長さ>)を(<メディア条件>を伴わずに)<source-size-list>のエントリとして使用することは無効ですが、解析アルゴリズムは、リストの任意の時点でそれを受け入れ、リストの先行するエントリが使用されていなかった場合に、すぐにそのサイズを受け入れます。これは将来の拡張を可能にし、単純な著者エラー(最後のコンマのようなもの)から保護するためです。裸のautoキーワードは、レガシーユーザーエージェントへのフォールバックを提供するために、他のエントリを後に続けることが許可されています。
画像ソースには、ピクセル密度記述子、幅記述子、またはURLに付随する記述子がない場合があります。ソースセットを正規化すると、すべての画像ソースにピクセル密度記述子が与えられます。
あるソースセットの密度を正規化するように要求された場合、ユーザーエージェントは次の操作を行う必要があります:
ユーザーエージェントは、環境の変化に反応するために、img要素の画像を更新するための以下のアルゴリズムをいつでも実行できます。(ユーザーエージェントは、このアルゴリズムを実行することを義務付けられているわけではありません。たとえば、ユーザーがページを見ていない場合、環境が再び変化する可能性があるため、どの画像を使用するかを判断する前に、ユーザーがページに戻るまで待つかもしれません。)
ユーザーがビューポートのサイズを変更したとき(例:ウィンドウのサイズ変更やページのズーム変更)、およびimg要素がドキュメントに挿入されたときに、このアルゴリズムを実行することが推奨されます。これにより、新しいビューポートに一致するように、密度補正された自然な幅と高さが一致し、アートディレクションが関係する場合に適切な画像が選択されます。
安定状態を待つ。同期セクションは、このアルゴリズムの残りのステップ全体で構成されます。このアルゴリズムが同期セクションが終了したと指示するまでです。(同期セクションのステップは、⌛でマークされています。)
⌛ img要素がsrcsetまたはpictureを使用していない場合、そのノードドキュメントが完全にアクティブでなく、画像データのリソースタイプがmultipart/x-mixed-replaceである場合、または保留中のリクエストがnullでない場合は、終了します。
⌛ 画像ソースを選択することにより、結果として得られるURLとピクセル密度をそれぞれ選択されたソースおよび選択されたピクセル密度とします。
⌛ 選択されたソースがnullの場合は終了します。
⌛ 選択されたソースと選択されたピクセル密度が要素の最後に選択されたソースおよび現在のピクセル密度と同じ場合は、終了します。
⌛ 選択されたソースを、要素のノードドキュメントに対してURLのエンコード、パース、およびシリアライズを行う結果として得られるurlStringとします。
⌛ urlStringが失敗した場合、終了します。
⌛ corsAttributeStateを要素のcrossoriginコンテンツ属性の状態とします。
⌛ clientをimg要素のノードドキュメントの関連設定オブジェクトとします。
⌛ keyをurlString、corsAttributeState、およびcorsAttributeStateがNo CORSでない場合のoriginからなるタプルとします。
⌛ 要素の保留中のリクエストをimage requestとします。
もし利用可能な画像のリストにkeyのエントリが含まれている場合、image requestの画像データをそのエントリのデータに設定します。次のステップに進みます。
それ以外の場合:
requestを潜在的CORSリクエストを作成する結果として得られるものとし、urlString、「image」、およびcorsAttributeStateを設定します。
requestのクライアントをclient、イニシエータを「imageset」に設定し、requestの同期フラグを設定します。
requestのリファラーポリシーを要素のreferrerpolicy属性の現在の状態に設定します。
requestの優先度を要素のfetchpriority属性の現在の状態に設定します。
requestの結果をフェッチの結果とします。
もしresponseの不安全な応答がネットワークエラーである場合、または画像形式がサポートされていない場合(画像スニッフィングルールを適用して決定)、またはimage
requestの画像が致命的な方法で破損しており、画像の寸法を取得できない場合、またはリソースタイプがmultipart/x-mixed-replaceである場合は、保留中のリクエストをnullに設定し、これらのステップを中止します。
それ以外の場合、responseの不安全な応答がimage requestの画像データとなります。それはCORS同一オリジンまたはCORSクロスオリジンのいずれかであり、これは他のAPIとの画像の相互作用に影響します(例:canvasで使用される場合)。
次のステップを使用して、img要素に対して要素タスクをキューに入れます:
もしこのアルゴリズムが開始されて以来、img要素に関連する突然変異が発生した場合、保留中のリクエストをnullに設定し、これらのステップを中止します。
img要素の最後に選択されたソースを選択されたソースとし、img要素の現在のピクセル密度を選択されたピクセル密度とします。
keyを使用して、画像を利用可能な画像のリストに追加し、上位レイヤーキャッシングを無視するフラグを設定します。
img要素を指定して、image
requestをプレゼンテーションのために準備します。
イベントを発火します。このイベントはloadという名前で、img要素で発生します。
特に指定がない限り、alt属性は指定されなければならず、その値は空であってはなりません。値は画像の適切な代替となるものでなければなりません。alt属性の具体的な要件は、以下のセクションで説明するように、画像が何を表現することを意図しているかに依存します。
代替テキストを書く際に考慮すべき最も一般的なルールは次のとおりです: すべての画像をそのalt属性のテキストに置き換えても、ページの意味が変わらないようにすることです。
したがって、一般的には、画像を含めることができなかった場合にどのように記述したかを考えることで、代替テキストを書くことができます。
このことから派生するのは、alt属性の値には、画像のキャプション、タイトル、または凡例と見なされる可能性のあるテキストを含めるべきではないということです。それは、画像の代わりにユーザーが使用できる代替テキストを含むべきであり、画像を補完するためのものではありません。補足情報にはtitle属性を使用できます。
もう一つの派生事項として、alt属性の値は、画像の横にある文章ですでに提供されている情報を繰り返してはなりません。
代替テキストを考える一つの方法は、画像が存在することに言及せずに、電話で誰かにページを読み上げる方法を考えることです。画像の代わりに言うことは、代替テキストを書く際の良い出発点となります。
a要素がハイパーリンクを作成する場合、またはbutton要素が、テキストコンテンツを持たず、1つ以上の画像のみを含む場合、alt属性にはリンクまたはボタンの目的を伝えるテキストを含める必要があります。
この例では、ユーザーは3つの中から好みの色を選択するよう求められます。それぞれの色は画像で表示されていますが、ユーザーエージェントを画像を表示しないように設定しているユーザーには、色の名前が代わりに使用されます:
< h1 > Pick your color</ h1 >
< ul >
< li >< a href = "green.html" > < img src = "green.jpeg" alt = "Green" > </ a ></ li >
< li >< a href = "blue.html" > < img src = "blue.jpeg" alt = "Blue" > </ a ></ li >
< li >< a href = "red.html" > < img src = "red.jpeg" alt = "Red" > </ a ></ li >
</ ul >
この例では、それぞれのボタンに、ユーザーが望む色出力の種類を示す一連の画像が設定されています。最初の画像が、各ケースで代替テキストを提供するために使用されています。
< button name = "rgb" > < img src = "red" alt = "RGB" >< img src = "green" alt = "" >< img src = "blue" alt = "" > </ button >
< button name = "cmyk" > < img src = "cyan" alt = "CMYK" >< img src = "magenta" alt = "" >< img src = "yellow" alt = "" >< img src = "black" alt = "" > </ button >
それぞれの画像がテキストの一部を表しているため、このように書くこともできます:
< button name = "rgb" > < img src = "red" alt = "R" >< img src = "green" alt = "G" >< img src = "blue" alt = "B" > </ button >
< button name = "cmyk" > < img src = "cyan" alt = "C" >< img src = "magenta" alt = "M" >< img src = "yellow" alt = "Y" >< img src = "black" alt = "K" > </ button >
ただし、他の代替テキストの場合、これでは機能しないこともあり、各ケースで全ての代替テキストを1つの画像にまとめる方が理にかなっているかもしれません:
< button name = "rgb" > < img src = "red" alt = "sRGB profile" >< img src = "green" alt = "" >< img src = "blue" alt = "" > </ button >
< button name = "cmyk" > < img src = "cyan" alt = "CMYK profile" >< img src = "magenta" alt = "" >< img src = "yellow" alt = "" >< img src = "black" alt = "" > </ button >
時には、フローチャート、図、グラフ、または道順を示す簡単な地図のように、グラフィカルな形式で表現した方がより明確になることがあります。このような場合、img要素を使用して画像を提供することができますが、画像を見ることができないユーザー(例えば、非常に遅い接続を使用しているため、テキストのみのブラウザを使用しているため、またはハンズフリーの自動車音声ウェブブラウザでページを読み上げているため、あるいは単に視覚障害があるため)でも伝えたいメッセージを理解できるように、より簡単なテキスト版も提供する必要があります。
テキストはalt属性に与えられ、src属性で指定された画像と同じメッセージを伝えなければなりません。
代替テキストは画像の代替であり、画像の説明ではないことを理解することが重要です。
以下の例では、画像形式のフローチャートがあり、alt属性のテキストでフローチャートがプローズ形式で書き換えられています:
< p > In the common case, the data handled by the tokenization stage
comes from the network, but it can also come from script.</ p >
< p > < img src = "images/parsing-model-overview.svg" alt = "The Network
passes data to the Input Stream Preprocessor, which passes it to the
Tokenizer, which passes it to the Tree Construction stage. From there,
data goes to both the DOM and to Script Execution. Script Execution is
linked to the DOM, and, using document.write(), passes data to the
Tokenizer." > </ p >
ここに、説明に画像を含める問題に対する良い解決策と悪い解決策を示す別の例があります。
まず、良い解決策です。このサンプルは、画像が存在しなかった場合にプローズで記述したであろう内容を代替テキストとすべきことを示しています。
<!-- This is the correct way to do things. -->
< p >
You are standing in an open field west of a house.
< img src = "house.jpeg" alt = "The house is white, with a boarded front door." >
There is a small mailbox here.
</ p >
次に、悪い解決策です。この間違った方法では、代替テキストが単に画像の説明になっているだけで、画像のテキストによる代替とはなっていません。画像が表示されないとき、最初の例ほどテキストが自然に流れないため、これは良くありません。
<!-- This is the wrong way to do things. -->
< p >
You are standing in an open field west of a house.
< img src = "house.jpeg" alt = "A white house, with a boarded front door." >
There is a small mailbox here.
</ p >
"Photo of white house with boarded door"のようなテキストも同様に悪い代替テキストとなります(ただし、これはtitle属性や、figcaption要素を持つfigureに適している場合があります)。
ドキュメントには、アイコン形式で情報を含めることができます。アイコンは、ビジュアルブラウザのユーザーが一目で機能を認識できるようにすることを意図しています。
場合によっては、アイコンが同じ意味を伝えるテキストラベルを補完するものとなっています。その場合、alt属性は存在しなければなりませんが、空でなければなりません。
ここでは、アイコンが同じ意味を伝えるテキストの隣にあるため、alt属性は空になっています:
< nav >
< p >< a href = "/help/" > < img src = "/icons/help.png" alt = "" > Help</ a ></ p >
< p >< a href = "/configure/" > < img src = "/icons/configuration.png" alt = "" >
Configuration Tools</ a ></ p >
</ nav >
他の場合では、アイコンの隣にその意味を説明するテキストがなく、アイコンは自己説明的であることが求められます。その場合、alt属性には同等のテキストラベルが与えられなければなりません。
ここでは、ニュースサイトの投稿にアイコンがラベルとして使用され、そのトピックを示しています。
< body >
< article >
< header >
< h1 > Ratatouille wins < i > Best Movie of the Year</ i > award</ h1 >
< p > < img src = "movies.png" alt = "Movies" > </ p >
</ header >
< p > Pixar has won yet another < i > Best Movie of the Year</ i > award,
making this its 8th win in the last 12 years.</ p >
</ article >
</ article >
< header >
< h1 > Latest TWiT episode is online</ h1 >
< p > < img src = "podcasts.png" alt = "Podcasts" > </ p >
</ header >
< p > The latest TWiT episode has been posted, in which we hear
several tech news stories as well as learning much more about the
iPhone. This week, the panelists compare how reflective their
iPhones' Apple logos are.</ p >
</ article >
</ body >
多くのページには、企業、組織、プロジェクト、バンド、ソフトウェアパッケージ、国など、特定のエンティティを表すロゴ、記章、旗、または紋章が含まれています。
ロゴがエンティティを表すために使用されている場合(例えば、ページの見出しとして)、alt属性には、ロゴによって表されるエンティティの名前を含める必要があります。alt属性に「ロゴ」という単語などのテキストを含めてはなりません。伝えられているのは、それがロゴであるという事実ではなく、エンティティそのものです。
ロゴがそれが表すエンティティの名前の隣に配置されている場合、そのロゴは補足的なものであり、alt属性は空でなければなりません。
ロゴが単に装飾として使用されている場合(ブランド化、または、例えば、ロゴが属するエンティティに言及している記事のサイド画像として使用されている場合)、純粋に装飾的な画像に関する以下の記述が適用されます。ロゴが実際に議論されている場合、それは代替グラフィカル表現を持つフレーズや段落(ロゴの説明)として使用されており、上記の最初の記述が適用されます。
以下のスニペットには、上記の4つのケースすべてが含まれています。まず、会社を表すために使用されているロゴを見てみましょう:
< h1 > < img src = "XYZ.gif" alt = "The XYZ company" > </ h1 >
次に、ロゴが会社名の隣に配置されている段落を見てみましょう。この場合、代替テキストはありません:
< article >
< h2 > News</ h2 >
< p > We have recently been looking at buying the < img src = "alpha.gif"
alt = "" > ΑΒΓ company, a small Greek company
specializing in our type of product.</ p >
この3番目のスニペットでは、記事全体の一部として、サイドにロゴが使用されています:
< aside >< p >< img src = "alpha-large.gif" alt = "" ></ p ></ aside >
< p > The ΑΒΓ company has had a good quarter, and our
pie chart studies of their accounts suggest a much bigger blue slice
than its green and orange slices, which is always a good sign.</ p >
</ article >
最後に、ロゴについて論じている意見記事があり、そのため、代替テキストに詳細が記述されています。
< p > Consider for a moment their logo:</ p >
< p >< img src = "/images/logo" alt = "It consists of a green circle with a
green question mark centered inside it." ></ p >
</ p > How unoriginal can you get? I mean, oooooh, a question mark, how
< em > revolutionary</ em > , how utterly </ em > ground-breaking</ em > , I'm
sure everyone will rush to adopt those specifications now! They could
at least have tried for some sort of, I don't know, sequence of
rounded squares with varying shades of green and bold white outlines,
at least that would look good on the cover of a blue book.</ p >
この例は、画像が表示されていない場合に、代替テキストが使用され、最初から画像がなかったかのように、テキストが周囲のテキストにシームレスに流れるように代替テキストが書かれるべきであることを示しています。
時には、画像がテキストだけで構成されており、その画像の目的は実際の書体効果を強調することではなく、単にテキストそのものを伝えることです。
そのような場合、alt属性は存在しなければなりませんが、画像に書かれているのと同じテキストで構成されなければなりません。
例えば、「Earth Day」というテキストが花や植物で飾られたグラフィックを考えてみてください。このテキストが単に見出しとして使用され、グラフィカルユーザーのためにページを華やかにするために使用されている場合、正しい代替テキストは「Earth Day」と同じテキストであり、装飾について言及する必要はありません:
< h1 > < img src = "earthdayheading.png" alt = "Earth Day" > </ h1 >
装飾写本では、いくつかの文字の画像にグラフィックが使用されることがあります。そのような状況では、代替テキストは画像が表す文字だけになります。
< p >< img src = "initials/o.svg" alt = "O" > nce upon a time and a long long time ago, late at
night, when it was dark, over the hills, through the woods, across a great ocean, in a land far
away, in a small house, on a hill, under a full moon...
画像がUnicodeで表現できない文字を表すために使用される場合、例えば外字、異体字、または新しい通貨記号のような新しい文字の場合、代替テキストは同じものをより一般的な方法で書いたものでなければなりません。例えば、その文字の発音を示すために、平仮名や片仮名を使用することができます。
1997年のこの例では、1本ではなく2本のバーが中央にある巻き毛のEのように見える新しい通貨記号が画像を使用して表されています。代替テキストには、その文字の発音が示されています。
< p > Only < img src = "euro.png" alt = "euro " > 5.99!
同じ目的を果たすことができる場合には、文字が使用されるべきです。例えば、装飾があるためにテキストで直接表現できない場合や、適切な文字が存在しない場合(外字の場合のように)、画像を使用することが適切です。
作成者がシステムのデフォルトフォントが特定の文字をサポートしていないために画像を使用したくなる場合、ウェブフォントは画像よりも優れた解決策です。
多くの場合、画像は実際には補足的なものであり、その存在は単に周囲のテキストを強調するためのものです。このような場合、alt属性は存在しなければなりませんが、その値は空の文字列でなければなりません。
一般的に、画像を削除してもページの有用性が損なわれることがなく、画像を含めることでビジュアルブラウザのユーザーが概念を理解しやすくなる場合、画像はこのカテゴリに該当します。
前の段落をグラフィカルに表現したフローチャート:
< p > The Network passes data to the Input Stream Preprocessor, which
passes it to the Tokenizer, which passes it to the Tree Construction
stage. From there, data goes to both the DOM and to Script Execution.
Script Execution is linked to the DOM, and, using document.write(),
passes data to the Tokenizer.</ p >
< p >< img src = "images/parsing-model-overview.svg" alt = "" ></ p >
このような場合、単なるキャプションを含む代替テキストを含めることは誤りです。キャプションを含める場合は、title属性を使用するか、figureおよびfigcaption要素を使用することができます。後者の場合、画像は実際には代替グラフィカル表現を持つフレーズや段落となり、代替テキストが必要になります。
<!-- Using the title="" attribute -->
< p > The Network passes data to the Input Stream Preprocessor, which
passes it to the Tokenizer, which passes it to the Tree Construction
stage. From there, data goes to both the DOM and to Script Execution.
Script Execution is linked to the DOM, and, using document.write(),
passes data to the Tokenizer.</ p >
< p > < img src = "images/parsing-model-overview.svg" alt = ""
title = "Flowchart representation of the parsing model." > </ p >
<!-- Using <figure> and <figcaption> -->
< p > The Network passes data to the Input Stream Preprocessor, which
passes it to the Tokenizer, which passes it to the Tree Construction
stage. From there, data goes to both the DOM and to Script Execution.
Script Execution is linked to the DOM, and, using document.write(),
passes data to the Tokenizer.</ p >
< figure >
< img src = "images/parsing-model-overview.svg" alt = "The Network leads to
the Input Stream Preprocessor, which leads to the Tokenizer, which
leads to the Tree Construction stage. The Tree Construction stage
leads to two items. The first is Script Execution, which leads via
document.write() back to the Tokenizer. The second item from which
Tree Construction leads is the DOM. The DOM is related to the Script
Execution." >
< figcaption > Flowchart representation of the parsing model.</ figcaption >
</ figure >
<!-- This is WRONG. Do not do this. Instead, do what the above examples do. -->
< p > The Network passes data to the Input Stream Preprocessor, which
passes it to the Tokenizer, which passes it to the Tree Construction
stage. From there, data goes to both the DOM and to Script Execution.
Script Execution is linked to the DOM, and, using document.write(),
passes data to the Tokenizer.</ p >
< p >< img src = "images/parsing-model-overview.svg"
alt = "Flowchart representation of the parsing model." ></ p >
<!-- Never put the image's caption in the alt="" attribute! -->
前の段落をグラフィカルに表現したグラフ:
< p > According to a study covering several billion pages,
about 62% of documents on the web in 2007 triggered the Quirks
rendering mode of web browsers, about 30% triggered the Almost
Standards mode, and about 9% triggered the Standards mode.</ p >
< p >< img src = "rendering-mode-pie-chart.png" alt = "" ></ p >
時には、画像がコンテンツにとって重要ではないものの、純粋に装飾的でもなく、テキストと完全に重複しているわけでもない場合があります。このような場合、alt属性は存在しなければならず、その値は空の文字列であるか、画像が伝える情報のテキスト表現である必要があります。画像にタイトルを示すキャプションがある場合、alt属性の値は空であってはなりません(視覚に頼らない読者にとって非常に混乱を招くためです)。
政治家についての記事で、その個人の顔が画像に表示されている状況を考えてみてください。画像は純粋に装飾的ではなく、記事に関連しています。また、画像は記事と完全に重複しているわけでもなく、政治家の外見を示しています。代替テキストを提供するかどうかは、画像が文章の解釈に影響を与えるかどうかに基づいて決定される、著者の判断です。
この最初のバリエーションでは、画像が文脈なしに表示され、代替テキストは提供されていません:
< p > < img src = "president.jpeg" alt = "" > Ahead of today's referendum,
the President wrote an open letter to all registered voters. In it, she admitted that the country was
divided.</ p >
もし写真がただの顔であれば、それを説明する価値はないかもしれません。個人が赤毛か金髪か、白い肌か黒い肌か、目が一つか二つかは、読者にとって関心のないことです。
しかし、写真がより動的で、例えば政治家が怒っている、特に喜んでいる、または悲嘆に暮れている様子を示している場合、代替テキストは記事のトーンを設定する上で役立つでしょう。そうでなければ、この記事が伝えるべきトーンが欠けてしまうかもしれません:
< p > < img src = "president.jpeg" alt = "The President is sad." >
Ahead of today's referendum, the President wrote an open letter to all
registered voters. In it, she admitted that the country was divided.
</ p >
< p > < img src = "president.jpeg" alt = "The President is happy!" >
Ahead of today's referendum, the President wrote an open letter to all
registered voters. In it, she admitted that the country was divided.
</ p >
個人が「悲しい」か「嬉しい」かは、段落の残り部分の解釈に影響を与えます。彼女は国が分断されていることに不満を示しているのか、それとも分断された国が彼女の政治的キャリアにとって良いと感じているのか?解釈は画像に基づいて変わります。
画像にキャプションがある場合、代替テキストを含めることで、視覚に頼らないユーザーがキャプションが何を指しているのかを理解するのを防ぐことができます。
< p > Ahead of today's referendum, the President wrote an open letter to
all registered voters. In it, she admitted that the country was divided.</ p >
< figure >
< img src = "president.jpeg"
alt = "A high forehead, cheerful disposition, and dark hair round out the President's face." >
< figcaption > The President of Ruritania. Photo © 2014 PolitiPhoto. </ figcaption >
</ figure >
画像が装飾的であるが、特にページ固有のものでない場合(例えば、サイト全体のデザインスキームの一部を構成する画像など)、その画像はドキュメントのマークアップではなく、サイトのCSSで指定されるべきです。
しかし、周囲のテキストで言及されていないが、それでもある程度の関連性がある装飾的な画像は、img要素を使用してページに含めることができます。このような画像は装飾的ですが、それでもコンテンツの一部を形成しています。このような場合、alt属性は存在しなければならず、その値は空の文字列でなければなりません。
画像が関連性があるにもかかわらず純粋に装飾的である例としては、バーニングマンのイベントについてのブログ記事に掲載されたブラックロックシティの風景写真や、詩を朗読するページに掲載されたその詩に触発された絵画の画像などが挙げられます。以下のスニペットは、後者のケースの例を示しています(このスニペットには最初の詩節のみが含まれています):
< h1 > The Lady of Shalott</ h1 >
< p >< img src = "shalott.jpeg" alt = "" ></ p >
< p > On either side the river lie< br >
Long fields of barley and of rye,< br >
That clothe the wold and meet the sky;< br >
And through the field the road run by< br >
To many-tower'd Camelot;< br >
And up and down the people go,< br >
Gazing where the lilies blow< br >
Round an island there below,< br >
The island of Shalott.</ p >
画像が小さな画像ファイルに分割され、それらが再び組み合わさって完全な画像を形成する場合、その画像の1つには、全体の画像に適用される適切な規則に従ってalt属性が設定されなければならず、残りのすべての画像にはalt属性が空の文字列として設定されなければなりません。
以下の例では、XYZ Corpの会社ロゴを表す画像が2つの部分に分割されています。最初の部分には「XYZ」という文字が含まれ、2番目の部分には「Corp」という文字が含まれています。代替テキスト「XYZ Corp」は最初の画像にすべて含まれています。
< h1 > < img src = "logo1.png" alt = "XYZ Corp" >< img src = "logo2.png" alt = "" > </ h1 >
次の例では、評価が3つの塗りつぶされた星と2つの空の星として表示されます。代替テキストは「★★★☆☆」とすることもできますが、著者はより親切に「5つ中3つ」として評価を示すことを選択しました。それが最初の画像の代替テキストであり、残りの画像には空の代替テキストが設定されています。
< p > Rating: < meter max = 5 value = 3 > < img src = "1" alt = "3 out of 5"
>< img src = "1" alt = "" >< img src = "1" alt = "" >< img src = "0" alt = ""
>< img src = "0" alt = "" > </ meter ></ p >
一般的には、リンク用に画像をスライスする代わりに、イメージマップを使用するべきです。
しかし、画像が実際にスライスされ、スライスされた画像のいずれかがリンクの唯一の内容となっている場合、リンクごとに1つの画像に、そのリンクの目的を表すalt属性に代替テキストが設定されなければなりません。
次の例では、飛んでいるスパゲッティモンスターの紋章を表す画像が、左側のヌードルの付属物と右側のヌードルの付属物が異なる画像で表現されており、ユーザーが冒険の中で左側または右側を選択できるようにしています。
< h1 > The Church</ h1 >
< p > You come across a flying spaghetti monster. Which side of His
Noodliness do you wish to reach out for?</ p >
< p >< a href = "?go=left" >< img src = "fsm-left.png" alt = "Left side. " ></ a
>< img src = "fsm-middle.png" alt = ""
>< a href = "?go=right" >< img src = "fsm-right.png" alt = "Right side." ></ a ></ p >
場合によっては、画像がコンテンツの重要な部分を占めることがあります。例えば、フォトギャラリーの一部であるページの場合、その画像がページ全体の要点であることがあります。
コンテンツの重要な部分である画像に対して代替テキストを提供する方法は、画像の出自に依存します。
詳細な代替テキストを提供できる場合、例えば、雑誌のレビューにおけるスクリーンショットの一部、漫画の一部、またはその写真に関するブログエントリの写真などの場合、その画像の代わりとなるテキストをalt属性の内容として提供する必要があります。
新しいOSのスクリーンショットギャラリーで、代替テキストが付いたスクリーンショット:
< figure >
< img src = "KDE%20Light%20desktop.png"
alt = "デスクトップは青で、左側にシステム、ホーム、K-Mailなどと
いったアイコンが2列に並んでいます。ウィンドウが開かれており、メニューが
ウィンドウに収まりきらない場合、次の行に折り返されることが示されています。
ウィンドウには上部にアイコンのリストがあり、その下にアドレスバーがあり、
左側にはタブ用のアイコンのリスト、下部にはステータスバーがあり、中央には
2つのペインがあります。デスクトップには画面下部にいくつかのボタン、ペイジャー、
開いているアプリケーションのリスト、および時計が配置されています。" >
< figcaption > KDEデスクトップのスクリーンショット。</ figcaption >
財務報告書のグラフ:
< img src = "sales.gif"
title = "売上グラフ"
alt = "1998年から2005年にかけて、各年の売上増加率は次の通りです: 624%、75%、138%、40%、35%、9%、21%" >
「売上グラフ」は、売上グラフにとって不十分な代替テキストであることに注意してください。キャプションとして適したテキストは、一般的に代替テキストとして適していません。
場合によっては、画像の性質上、詳細な代替テキストを提供することが実際には難しいことがあります。例えば、画像が不明瞭であったり、複雑なフラクタルであったり、詳細な地形図である場合です。
このような場合でも、alt属性には適切な代替テキストが含まれている必要がありますが、多少簡潔なものでも構いません。
場合によっては、画像を適切に説明できるテキストが存在しないことがあります。例えば、ロールシャッハのインクブロットテストを有効に説明できるテキストはほとんどありません。しかし、簡潔であっても、何もないよりは良いです:
< figure >
< img src = "/commons/a/a7/Rorschach1.jpg" alt = "左右対称で縁が不明瞭な形状、中央に小さな隙間、中央から少しずれたところに2つの大きな隙間、その下に似た隙間が2つあります。輪郭は上半分が下半分よりも広く、側面は中央よりも上に伸び、中央は側面よりも下に伸びています。" >
< figcaption > ロールシャッハ・インクブロットテストの最初の10枚のカードのうちの1枚の黒い輪郭。</ figcaption >
以下のような代替テキストの使用は非常に悪い例です:
<!-- この例は間違っています。コピーしないでください。 -->
< figure >
< img src = "/commons/a/a7/Rorschach1.jpg" alt = "ロールシャッハ・インクブロットテストの最初の10枚のカードのうちの1枚の黒い輪郭。" >
< figcaption > ロールシャッハ・インクブロットテストの最初の10枚のカードのうちの1枚の黒い輪郭。</ figcaption >
</ figure >
このようにキャプションを代替テキストに含めることは有用ではありません。画像を表示できないユーザーに対してキャプションを二重に提供することになり、1回だけキャプションを読んだり聞いたりするよりも助けになりません。
フラクタルなど、定義上無限の詳細を持つ画像も、完全な説明が難しい例です。
以下の例は、マンデルブロ集合の画像全体に対して代替テキストを提供する方法の一例です。
< img src = "ms1.jpeg" alt = "マンデルブロ集合は、正の方向にある実軸上の尖点を持つ心臓型で、負の方向に接触する小さな球体が同じ中心線に沿って配置されており、これら2つの形状がさまざまなサイズの小さな球体に囲まれています。" >
同様に、例えば伝記に掲載されている人物の顔写真なども、コンテンツにとって非常に重要であると考えられることがありますが、完全に代替できるテキストを提供するのは難しいことがあります:
< section class = "bio" >
< h1 > アイザック・アシモフの伝記</ h1 >
< p > アイザックは1920年にアイザック・ユードヴィッチ・オズィモフとして生まれ、非常に多作な作家でした。</ p >
< p >< img src = "headpics/asimov.jpeg" alt = "アイザック・アシモフは黒髪で、高い額とメガネをかけていました。後年には、長い白いもみあげをしていました。" ></ p >
< p > アシモフはロシアで生まれ、3歳のときに米国に移住しました。</ p >
</ p > ...</ p >
</ section >
このような場合、代替テキストに画像自体の存在に言及する必要はなく(むしろ避けるべきです)、そのようなテキストはブラウザ自体が画像の存在を報告することと重複するためです。例えば、「アイザック・アシモフの写真」という代替テキストを使用した場合、準拠したユーザーエージェントは「(画像)アイザック・アシモフの写真」と読み上げるかもしれず、「(画像)アイザック・アシモフは黒髪で、高い額とメガネをかけていました…」のほうが有用です。
残念ながら、代替テキストがまったく提供されない場合もあります。例えば、画像が自動的に取得され、関連する代替テキストが提供されていない場合(例:ウェブカメラ)や、ユーザーが提供した画像を使用してページがスクリプトで生成されるが、ユーザーが適切な代替テキストを提供しなかった場合(例:写真共有サイト)や、著者自体が画像の内容を知らない場合(例:盲目の写真家がブログに画像を共有する場合)などです。
このような場合、alt属性は省略しても構いませんが、次の条件のいずれかを満たす必要があります。
img要素がfigure要素内にあり、figcaption要素がfigure要素の中で唯一のコンテンツであり、その中にimg要素が存在していること。
title属性が存在し、その値が空でないこと。
title属性に依存することは現在は推奨されていません。多くのユーザーエージェントは、マウスなどのポインティングデバイスが必要であるため、この属性を仕様で求められるようにアクセシブルに公開していない場合があります。これは、キーボードのみのユーザーや、現代の電話やタブレットを使用しているタッチユーザーなど、特定のユーザーにとっては困難です。
このようなケースは可能な限り最小限に抑える必要があります。著者が実際に代替テキストを提供できる可能性がわずかでもある場合には、alt属性を省略することは許されません。
写真共有サイトで、サイトがキャプション以外のメタデータを持たずに画像を受け取った場合、そのようにマークアップできます:
< figure >
< img src = "1100670787_6a7c664aef.jpg" >
< figcaption > 私たちと一緒にどこへでも旅したバブルス。</ figcaption >
</ figure >
ただし、画像の重要な部分について詳細な説明をユーザーから取得し、ページに含めるのが望ましいです。
盲目のユーザーのブログに、ユーザーが撮影した写真が表示されている場合です。最初は、ユーザーが撮影した写真が何を示しているかがわからないかもしれません:
< article >
< h1 > 私は写真を撮りました</ h1 >
< p > 今日は外出して写真を撮りました!</ p >
< figure >
< img src = "photo2.jpeg" >
< figcaption > 私のポーチから盲目的に撮影された写真。</ figcaption >
</ figure >
</ article >
その後、ユーザーが友人から画像の説明を得て、代替テキストを含めることができるようになります:
< article >
< h1 > 私は写真を撮りました</ h1 >
< p > 今日は外出して写真を撮りました!</ p >
< figure >
< img src = "photo2.jpeg" alt = "写真には、私の屋根の縁から吊り下げられているリスの餌箱が写っています。餌箱は半分しか満たされておらず、リスは見当たりません。背景には、ぼやけた木々が写っています。餌箱は木製で、金属製の格子があり、中にはピーナッツが入っています。屋根の縁も木製で、白く塗られ、青い縞模様が入っています。" >
< figcaption > 私のポーチから盲目的に撮影された写真。</ figcaption >
</ article >
場合によっては、画像の要点がテキスト説明が利用できないことであり、ユーザーが説明を提供する必要がある場合もあります。例えば、CAPTCHA画像の要点は、ユーザーがグラフィックを実際に読むことができるかどうかを確認することです。以下はCAPTCHAをマークアップする方法の一例です(title属性に注意してください):
< p >< label > この画像には何が書かれていますか?
< img src = "captcha.cgi?id=8934" title = "CAPTCHA" >
< input type = text name = captcha ></ label >
(画像が表示できない場合は、< a href = "?audio" > 音声テスト</ a > を使用できます。)</ p >
別の例として、画像を表示して代替テキストを求めるソフトウェアがあり、その目的は正しい代替テキストを提供するページを作成することです。このようなページには、次のように画像の表が含まれることがあります:
< table >
< thead >
< tr > < th > 画像 < th > 説明
</ tbody >
< tr >
< td > < img src = "2421.png" title = "画像640x100、ファイル名 'banner.gif'" >
< td > < input name = "alt2421" >
</ tr >
< td > < img src = "2422.png" title = "画像200x480、ファイル名 'ad3.gif'" >
< td > < input name = "alt2422" >
</ table >
この例でも、可能な限り有用な情報がtitle属性に含まれていることに注意してください。
一部のユーザーは、画像をまったく使用できない場合があります(例:非常に遅い接続のため、テキストのみのブラウザを使用しているため、ハンズフリーの自動車音声ウェブブラウザでページが読み上げられているため、単に視覚障害があるためなど)。したがって、上記の例のように代替テキストが利用できず、提供できない場合にのみ、alt属性を省略することが許可されます。著者の努力不足は、alt属性を省略する正当な理由ではありません。
一般的に、著者はimg要素を画像表示以外の目的で使用することを避けるべきです。
もしimg要素が、例えばページビューをカウントするサービスの一部として画像表示以外の目的で使用される場合、alt属性は空の文字列にする必要があります。
そのような場合、width属性とheight属性は両方ともゼロに設定すべきです。
このセクションは、公開アクセス可能なドキュメントや、著者が個人的に知らない可能性のあるターゲットオーディエンスを持つドキュメント(例えばウェブサイト上のドキュメント、公開メールリストに送信されたメール、ソフトウェアドキュメントなど)には適用されません。
特定の人物に向けたプライベートなコミュニケーション(HTMLメールなど)で、その人物が画像を表示できることがわかっている場合には、alt属性を省略することができます。ただし、そのような場合でも、ユーザーが画像をサポートしないメールクライアントを使用した場合や、ドキュメントが他のユーザーに転送された場合に備えて、適切な代替テキストを含めることが強く推奨されます。
マークアップジェネレーター(WYSIWYGオーサリングツールなど)は、可能な限りユーザーから代替テキストを取得する必要があります。しかし、多くの場合、これが不可能であることも認識されています。
リンクの唯一の内容である画像の場合、マークアップジェネレーターはリンク先のタイトルやURLを調べ、得られた情報を代替テキストとして使用する必要があります。
キャプションがある画像については、マークアップジェネレーターはfigureおよびfigcaption要素、またはtitle属性を使用して画像のキャプションを提供する必要があります。
最終手段として、実装者は、画像が周囲のコンテンツに特有であるが情報を追加しない純粋に装飾的な画像であると想定してalt属性を空の文字列に設定するか、画像がコンテンツの重要な部分であると想定してalt属性をまったく省略する必要があります。
マークアップジェネレーターは、代替テキストを取得できなかったimg要素に対して属性を指定することができます。この属性の値は空の文字列でなければなりません。このような属性を含むドキュメントは適合していませんが、適合チェッカーはこのエラーを静かに無視します。generator-unable-to-provide-required-alt
これは、最先端の自動適合チェッカーが偽の代替テキストと正しい代替テキストを区別できないために、マークアップジェネレーターが適合チェッカーを黙らせるためだけに偽の代替テキストを提供するという更に悪質なエラーに置き換える圧力を避けることを目的としています。
マークアップジェネレーターは、一般に画像自体のファイル名を代替テキストとして使用することを避けるべきです。同様に、マークアップジェネレーターはプレゼンテーションユーザーエージェント(例:ウェブブラウザ)にも同様に利用可能なコンテンツから代替テキストを生成することを避けるべきです。
これは、ページが生成されると通常は更新されませんが、その後にページを読み取るブラウザはユーザーによって更新される可能性があるため、ブラウザはページを生成したときのマークアップジェネレーターよりも、より最新で精緻化されたヒューリスティックを持っている可能性が高いためです。
適合チェッカーは、次の条件のいずれかが該当しない限り、alt属性の欠如をエラーとして報告しなければなりません:
適合チェッカーが、ドキュメントが画像を表示できることがわかっている特定の人物に向けたメールまたはドキュメントであると仮定するように設定されている場合。
img要素が、値が空の文字列であるgenerator-unable-to-provide-required-alt属性(適合していない属性)を持つ場合。alt属性が欠如していることをエラーとして報告しない適合チェッカーは、空のgenerator-unable-to-provide-required-alt属性の存在もエラーとして報告してはなりません(この場合、ドキュメントが適合しているわけではなく、ジェネレーターが適切な代替テキストを決定できなかったことを示しています。検証者はこの場合エラーを示す必要はありませんが、そのようなエラーは、マークアップジェネレーターが検証者を黙らせるためだけに偽の代替テキストを含めることを促す可能性があるためです。自然に、適合チェッカーはalt属性が欠如していることをエラーとして報告する場合もあります。例えば、マークアップジェネレーターの使用の結果としてほぼ必然的に発生するエラーであっても、すべての適合エラーを報告するオプションをユーザーに提供することができます。)
iframe要素
すべての現行エンジンでサポートされています。
すべての現行エンジンでサポートされています。
src — リソースのアドレス
srcdoc — iframe内に表示するドキュメント
name — ナビゲーション可能なコンテンツの名前
sandbox —
ネストされたコンテンツのセキュリティルール
allow — Permissions
policyをiframeのコンテンツに適用
allowfullscreen
— iframeのコンテンツがrequestFullscreen()を使用できるかどうか
width — 横方向のサイズ
height — 縦方向のサイズ
referrerpolicy
— リファラーポリシーをフェッチで適用する
loading —
ローディングの遅延を決定する際に使用される
[Exposed =Window ]
interface HTMLIFrameElement : HTMLElement {
[HTMLConstructor ] constructor ();
[CEReactions ] attribute USVString src ;
[CEReactions ] attribute (TrustedHTML or DOMString ) srcdoc ;
[CEReactions ] attribute DOMString name ;
[SameObject , PutForwards =value ] readonly attribute DOMTokenList sandbox ;
[CEReactions ] attribute DOMString allow ;
[CEReactions ] attribute boolean allowFullscreen ;
[CEReactions ] attribute DOMString width ;
[CEReactions ] attribute DOMString height ;
[CEReactions ] attribute DOMString referrerPolicy ;
[CEReactions ] attribute DOMString loading ;
readonly attribute Document ? contentDocument ;
readonly attribute WindowProxy ? contentWindow ;
Document ? getSVGDocument ();
// also has obsolete members
};
iframe
要素は、そのナビゲーション可能なコンテンツを表します。
src
属性は、要素のURL
を指定し、そのナビゲーション可能なコンテンツを含むべきです。この属性が存在する場合、それは有効な非空のURLであり、空白に囲まれている可能性があります。itemprop
属性がiframe要素に指定されている場合は、src属性も指定する必要があります。
すべての現行エンジンでサポートされています。
srcdoc
属性は、その要素のナビゲーション可能なコンテンツを含むべきページの内容を指定します。この属性の値は、構築に使用されます。iframe srcdocドキュメントを構成するDocumentのURLは、about:srcdocと一致します。
srcdoc
属性が存在する場合、その値はHTML構文を使用し、以下の構文要素を順番に含む必要があります:
html形式の要素。
上記の要件はXMLドキュメントにも適用されます。
ここでは、ブログがsrcdoc
属性をsandbox属性と組み合わせて使用し、この機能をサポートするユーザーエージェントのユーザーに、ブログ投稿コメントにおけるスクリプトインジェクションからの保護のための追加の保護層を提供しています:
< article >
< h1 > 私は自分の雑誌を手に入れました!</ h1 >
< p > 多くの努力の末、ついに出版社を見つけ、今や自分の雑誌を持っています!素晴らしいでしょ?!9月に最初の号が発行され、食べ物を手に入れる方法や、箱に入る方法に関する記事があります。とても素晴らしいです!</ p >
< footer >
< p > 執筆者 < a href = "/users/cap" > cap</ a > , 1時間前。
</ footer >
</ article >
< footer > 13分前、< a href = "/users/ch" > ch</ a > は書いた: </ footer >
< iframe sandbox srcdoc = "<p>カバー写真はもう撮れましたか?" ></ iframe >
</ article >
< article >
< footer > 9分前、< a href = "/users/ch" > ch</ a > は書いた: </ footer >
< iframe sandbox srcdoc = "<p>ええ、私のギャラリーで見られます <a href="/gallery?mode=cover&amp;page=1">ここ</a>で。" ></ iframe >
</ article >
< article >
< footer > 5分前、< a href = "/users/ch" > ch</ a > は書いた: </ footer >
< iframe sandbox srcdoc = "<p>それはアールのテーブルです。<p>次号の表紙にはアール&amp;私を載せるべきです。" ></ iframe >
</ article >
引用符がどのようにエスケープされなければならないか(さもなければsrcdoc属性が早期に終了してしまう)、およびサンドボックス化されたコンテンツで言及される生のアンパサンド(例えばURLやプローズ内で)がどのように二重にエスケープされる必要があるかに注意してください—一度目は元の解析時にアンパサンドが保持されるため、二度目はサンドボックス化されたコンテンツを解析する際にアンパサンドが誤解釈されないようにするためです。
さらに、DOCTYPEがiframe
srcdocドキュメントではオプションであり、html、head、およびbody要素には開始タグと終了タグが省略可能であり、title要素もiframe
srcdocドキュメントではオプションであることに注意してください。そのため、srcdoc属性内のマークアップは、ドキュメント全体を表現しているにもかかわらず、比較的簡潔にすることができます。これは、body要素の内容のみが文法に直接記述される必要があり、他の要素は暗黙的に存在しているからです。
HTML構文では、著者はU+0022引用符文字(")を使用して属性の内容を囲み、その後にすべてのU+0026アンパサンド(&)およびU+0022引用符(")文字をエスケープし、さらに安全なコンテンツ埋め込みを保証するためにsandbox属性を指定することを覚えておくだけで済みます。(引用符の前にアンパサンドをエスケープし、引用符が"となり、&quot;にならないようにすることを忘れないでください。)
XMLでは、U+003C小なり記号(<)もエスケープする必要があります。属性値の正規化を防ぐために、XMLのいくつかの空白文字、特にU+0009タブ(tab)、U+000Aラインフィード(LF)、およびU+000Dキャリッジリターン(CR)もエスケープする必要があります。[XML]
src属性とsrcdoc属性が両方指定されている場合、srcdoc属性が優先されます。これにより、srcdoc属性をサポートしないレガシーユーザーエージェントのために、フォールバックURLを提供できます。
iframeのHTML要素挿入ステップは、insertedNodeを指定して次の通りです:
insertedNodeのシャドウを含むルートのブラウジングコンテキストが nullであれば、終了します。
insertedNodeのために新しい子ナビゲーブルを作成します。
insertedNodeにsandbox
属性がある場合、その属性の値とinsertedNodeのiframeサンドボックスフラグセットを指定してサンドボックスディレクティブを解析します。
initialInsertionをtrueに設定し、insertedNodeのiframe属性を処理します。
iframeのHTML要素削除ステップは、removedNodeを指定して子ナビゲーブルを破壊することです。
これは、unloadイベントが発生せずに行われます
(要素のコンテンツドキュメントは破壊されますが、unloadされるわけではありません)。
iframeはシャドウツリー内で処理されますが、
上記に従い、その動作のいくつかの側面はシャドウツリーに関して明確に定義されていません。詳細はissue
#763を参照してください。
iframe
要素に非nullのナビゲーション可能なコンテンツがあり、
srcdoc属性が設定、変更、または削除された場合、
ユーザーエージェントはiframe属性を処理しなければなりません。
同様に、非nullのナビゲーション可能なコンテンツを持ち、srcdoc属性が指定されていないiframe要素において、
src属性が設定、変更、または削除された場合、
ユーザーエージェントはiframe属性を処理しなければなりません。
elementに対してiframe属性を処理するには、
任意のブール値initialInsertion
(デフォルトはfalse)を指定します:
もしelementのsrcdoc
属性が
指定されている場合:
elementの現在のナビゲーションは遅延ロードされていたブール値をfalseに設定します。
要素を遅延ロードするかどうかのステップをelementに対して実行し、trueを返す場合は:
elementの遅延ロード再開ステップを、このアルゴリズムのsrcdocリソースへナビゲートというラベルのステップから始めるように設定します。
elementの現在のナビゲーションは遅延ロードされていたブール値をtrueに設定します。
elementのために遅延ロード要素のインターセクション監視を開始します。
終了します。
srcdocリソースへナビゲート: element、about:srcdoc、空文字列、およびelementのsrcdoc属性の値を指定してiframeまたはframeをナビゲートします。
生成されたDocumentはiframe
srcdocドキュメントと見なさなければなりません。
それ以外の場合:
elementとinitialInsertionを指定してiframeおよびframe要素の共有属性処理ステップを実行し、その結果をurlに設定します。
もしurlがnullであれば、終了します。
urlがabout:blankと一致し、initialInsertionがtrueである場合:
elementを指定してiframeロードイベントステップを実行します。
終了します。
elementのreferrerpolicy
コンテンツ属性の現在の状態をreferrerPolicyに設定します。
elementの現在のナビゲーションは遅延ロードされていたブール値をfalseに設定します。
要素を遅延ロードするかどうかのステップをelementに対して実行し、trueを返す場合:
elementの遅延ロード再開ステップを、このアルゴリズムのnavigateというラベルのステップから始めるように設定します。
elementの現在のナビゲーションは遅延ロードされていたブール値をtrueに設定します。
elementのために遅延ロード要素のインターセクション監視を開始します。
終了します。
ナビゲート: element、url、およびreferrerPolicyを指定してiframeまたはframeをナビゲートします。
elementおよびブール値initialInsertionを指定してiframeおよびframe要素の共有属性処理ステップを実行するには:
urlをURLレコードのabout:blankに設定します。
elementにsrc属性が指定されており、その値が空文字列でない場合:
その属性の値をelementのノードドキュメントに対して相対的にURLをエンコーディングして解析します結果をmaybeURLに設定します。
もしmaybeURLが失敗でない場合、urlをmaybeURLに設定します。
elementのノードナビゲーブルの包括的先祖ナビゲーブルに、urlを等しいと見なせるアクティブドキュメントを持つナビゲーブルが含まれている場合、nullを返します。
urlがabout:blankと一致し、 initialInsertionがtrueである場合、elementのナビゲーション可能なコンテンツのアクティブドキュメントとurlを指定してURLおよび履歴更新ステップを実行します。
これは、urlがabout:blank?fooのようなものである場合に必要です。もしurlが単なるabout:blankである場合、これは何もしません。
urlを返します。
element、url、referrerPolicy、およびオプションでsrcdocString(デフォルトはnull)を指定してiframeまたはframeをナビゲートしますには:
historyHandlingを"auto"に設定します。
elementのナビゲーション可能なコンテンツのアクティブドキュメントが完全にロードされていない場合、
historyHandlingを"replace"に設定します。
もしelementがiframeである場合、
elementの保留中のリソースタイミング開始時間を
elementのノードドキュメントの関連するグローバルオブジェクトを指定して現在の高解像度時間に設定します。
elementのナビゲーション可能なコンテンツをurlにナビゲートし、elementのノードドキュメントを使用し、historyHandlingを設定し、 referrerPolicyを設定し、srcdocStringをドキュメントリソースとして設定します。
各Documentにはiframeロード進行中フラグとiframeロードミュートフラグがあります。Documentが作成されたとき、これらのフラグはそのDocumentに対して未設定でなければなりません。
elementを指定してiframeロードイベントステップを実行するには:
アサート: elementのナビゲーション可能なコンテンツがnullでないこと。
childDocumentをelementのナビゲーション可能なコンテンツのアクティブドキュメントに設定します。
もしchildDocumentがそのiframeロードミュートフラグを設定している場合、終了します。
elementの保留中のリソースタイミング開始時間が nullでない場合:
elementのノードドキュメントの 関連するグローバルオブジェクトをglobalに設定します。
globalを指定してフェッチタイミング情報を新たに作成し、 開始時間をelementの 保留中のリソースタイミング開始時間 に設定し、応答終了時間を globalを指定して現在の高解像度時間に設定します。
fallbackTimingInfo、url、
"iframe"、
global、空文字列、新しい
応答本文情報、および0を指定してリソースタイミングをマークします。
elementの保留中のリソースタイミング開始時間 をnullに設定します。
childDocumentのiframeロード進行中フラグを設定します。
childDocumentのiframeロード進行中フラグを解除します。
これは、スクリプティングと組み合わせることで、ローカルネットワークのHTTPサーバーのURLスペースを探索するために使用できます。ユーザーエージェントは、この攻撃を軽減するために、上記よりも厳しいクロスオリジンアクセス制御ポリシーを実装することがありますが、残念ながらそのようなポリシーは通常、既存のウェブコンテンツとの互換性がありません。
要素タイプがロードイベントを遅延させる可能性がある場合、そのタイプの各要素elementについて、ユーザーエージェントは、elementのナビゲーション可能なコンテンツが非nullであり、次のいずれかが当てはまる場合、そのelementのノードドキュメントのロードイベントを遅延させます:
elementのナビゲーション可能なコンテンツのアクティブドキュメントがロード後のタスクの準備ができていない;
elementのナビゲーション可能なコンテンツのloadイベントを遅延させるモードが
trueである;または
何かがelementのナビゲーション可能なコンテンツのアクティブドキュメントのロードイベントを遅延させています。
elementのナビゲーション可能なコンテンツが再びナビゲートされると、loadイベントの処理中にそのロードイベントがさらに遅延します。
iframe
要素には、
現在のナビゲーションが遅延ロードされたブール値が関連付けられており、初期状態ではfalseです。これは、iframe属性を処理するアルゴリズムで設定および解除されます。
iframe
要素の
現在のナビゲーションが遅延ロードされたブール値がfalseの場合、その要素はロードイベントを遅延させる可能性があります。
iframe
要素には、
nullまたはDOMHighResTimeStamp保留中のリソースタイミング開始時間が関連付けられており、初期状態ではnullに設定されています。
要素が作成されたとき、srcdoc属性が設定されておらず、
src属性が
設定されていないか、設定されていてもその値が解析できない場合、
要素のナビゲーション可能なコンテンツは、初期のabout:blankのDocumentに留まります。
ユーザーがこのページからナビゲートした場合、
iframeのナビゲーション可能なコンテンツのアクティブWindowProxyオブジェクトは新しいWindowオブジェクトを新しいDocumentオブジェクトにプロキシしますが、src属性は変更されません。
name属性が存在する場合、その値は有効なナビゲーションターゲット名でなければなりません。指定された値は、コンテンツナビゲーションが存在する場合に、その要素の名前として使用されます。
すべての現行エンジンでサポートされています。
sandbox属性が指定されている場合、iframe内にホストされるコンテンツに追加の制限が適用されます。その値は、順不同の一意なスペース区切りトークンのセットでなければなりません。これらのトークンはASCIIケースインセンシティブでなければなりません。指定可能な値は以下の通りです:
allow-downloads
allow-forms
allow-modals
allow-orientation-lock
allow-pointer-lock
allow-popups
allow-popups-to-escape-sandbox
allow-presentation
allow-same-origin
allow-scripts
allow-top-navigation
allow-top-navigation-by-user-activation
allow-top-navigation-to-custom-protocols
この属性が設定されると、コンテンツは不透明なオリジンからのものであると見なされ、フォーム、スクリプト、および潜在的に迷惑なAPIが無効になり、リンクは他のナビゲーブルをターゲットにすることができなくなります。allow-same-originキーワードは、コンテンツが不透明なオリジンに強制されるのではなく、その実際のオリジンからのものであると見なされるようにします。allow-top-navigationキーワードは、コンテンツがそのトラバースナビゲーブルをナビゲートできるようにします。また、allow-top-navigation-by-user-activationキーワードは、同様の動作をしますが、ブラウジングコンテキストのアクティブウィンドウが一時的なアクティベーションを持つ場合にのみ、そのようなナビゲーションを許可します。allow-top-navigation-to-custom-protocolsキーワードは、非フェッチスキームへのナビゲーションを外部ソフトウェアに引き渡すことを再度有効にします。そして、allow-forms、allow-modals、allow-orientation-lock、allow-pointer-lock、allow-popups、allow-presentation、allow-scripts、およびallow-popups-to-escape-sandboxキーワードは、それぞれフォーム、モーダルダイアログ、画面の向きロック、ポインタロックAPI、ポップアップ、プレゼンテーションAPI、スクリプト、およびサンドボックス化されていない補助ブラウジングコンテキストの作成を再度有効にします。allow-downloadsキーワードは、コンテンツがダウンロードを実行できるようにします。[POINTERLOCK] [SCREENORIENTATION] [PRESENTATION]
allow-top-navigationおよびallow-top-navigation-by-user-activationキーワードは、両方とも指定してはいけません。このような非準拠のマークアップでは、allow-top-navigationのみが効果を持ちます。
同様に、allow-top-navigation-to-custom-protocolsキーワードは、allow-top-navigationまたはallow-popupsのいずれかが指定されている場合には指定してはいけません。これは冗長です。
サンドボックス化されたコンテンツ内でalert()、confirm()、およびprompt()を許可するには、allow-modalsおよびallow-same-originキーワードを両方指定する必要があり、読み込まれたURLが同一オリジンであり、トップレベルのオリジンと一致する必要があります。allow-same-originキーワードがないと、コンテンツは常にクロスオリジンとして扱われ、クロスオリジンコンテンツはシンプルダイアログを表示できません。
allow-scriptsとallow-same-originキーワードを、埋め込まれたページがページコンテンツと同一オリジンである場合に一緒に設定すると、埋め込まれたページは単にsandbox属性を削除して自分自身をリロードするだけで、事実上サンドボックスを完全に回避することができます。
これらのフラグは、iframe要素のコンテンツナビゲーブルがナビゲートされるときにのみ効果を発揮します。これらを削除したり、sandbox属性全体を削除しても、すでにロードされているページには影響を与えません。
潜在的に危険なファイルは、iframe要素を含むファイルと同じサーバーから提供されるべきではありません。攻撃者がユーザーを直接その悪意のあるコンテンツに誘導することができる場合、サンドボックス化はほとんど役に立ちません。悪意のあるHTMLコンテンツによって引き起こされる可能性のある被害を制限するために、それは専用の別のドメインから提供されるべきです。異なるドメインを使用することで、ユーザーがそのページに直接アクセスするようにだまされた場合でも、ファイル内のスクリプトがサイトを攻撃できなくなります。これは、sandbox属性の保護なしで実行される可能性があるからです。
iframe 要素の sandbox 属性が設定または変更され、それが
null でない コンテンツナビゲーブル
を持っている場合、ユーザーエージェントは サンドボックスディレクティブを解析 し、その属性の値とその iframe 要素の iframe
サンドボックスフラグセット を基に処理を行います。
iframe 要素の sandbox 属性が削除され、それが null
でない コンテンツナビゲーブル を持っている場合、ユーザーエージェントはその
iframe 要素の iframe
サンドボックスフラグセット を空にする必要があります。
この例では、完全に未知の、潜在的に危険な、ユーザー提供の HTML コンテンツがページに埋め込まれています。別のドメインから提供されているため、通常のクロスサイト制限が適用されます。さらに、埋め込まれたページはスクリプト、プラグイン、フォームが無効化されており、自身以外のフレームやウィンドウ(または自身が埋め込んだフレームやウィンドウ)をナビゲートすることはできません。
< p > We're not scared of you! Here is your content, unedited:</ p >
< iframe sandbox src = "https://usercontent.example.net/getusercontent.cgi?id=12193" ></ iframe >
攻撃者がユーザーを直接そのページに誘導しようとする場合、ページがサイトのオリジンのコンテキストで実行されないように、別のドメインを使用することが重要です。これにより、ページ内で発見された攻撃に対してユーザーが脆弱になるのを防ぎます。
この例では、別のサイトからのガジェットが埋め込まれています。ガジェットにはスクリプトとフォームが有効で、オリジンサンドボックスの制限が解除され、ガジェットがその起源サーバーと通信できるようになっています。それでもサンドボックスは有効であり、プラグインやポップアップが無効化されているため、ユーザーがマルウェアやその他の迷惑なものにさらされるリスクが軽減されます。
< iframe sandbox = "allow-same-origin allow-forms allow-scripts"
src = "https://maps.example.com/embedded.html" ></ iframe >
ファイル A に次の断片が含まれていたとします:
< iframe sandbox = "allow-same-origin allow-forms" src = B ></ iframe >
ファイル B にも iframe が含まれていたとします:
< iframe sandbox = "allow-scripts" src = C ></ iframe >
さらに、ファイル C にリンクが含まれていたとします:
< a href = D > Link</ a >
この例では、すべてのファイルがtext/htmlとして提供されていると仮定します。
このシナリオでは、ページ C にはすべてのサンドボックスフラグが設定されています。スクリプトは無効になっています。これは、A の iframe
でスクリプトが無効になっているためであり、これにより B の allow-scripts
キーワードが上書きされます。フォームも無効になっています。これは、B の内部の iframe が allow-forms
キーワードを持っていないためです。
今、A のスクリプトが A と B のすべての sandbox
属性を削除したと仮定します。これにより、すぐには何も変わりません。ユーザーが C のリンクをクリックし、ページ D を B の iframe にロードすると、ページ D
は B の iframe に
allow-same-origin
および allow-forms
キーワードが設定されていたかのように動作します。なぜなら、それはページ B が読み込まれたときの A の コンテンツナビゲーブル の状態だったからです。
一般的に言って、動的に sandbox
属性を削除または変更することはお勧めできません。なぜなら、何が許可され、何が許可されないかを論理的に判断することが非常に難しくなる可能性があるからです。
allow 属性が指定された場合、コンテナポリシー
が決定され、それが 権限ポリシー として使用されます。これは、Document が iframe の コンテンツナビゲーブル 内で初期化されるときに適用されます。その値は、シリアライズされた権限ポリシーである必要があります。[PERMISSIONSPOLICY]
この例では、iframe
を使用して、オンラインナビゲーションサービスから地図を埋め込んでいます。allow 属性は、ネストされたコンテキスト内で
Geolocation API を有効にするために使用されています。
< iframe src = "https://maps.example.com/" allow = "geolocation" ></ iframe >
allowfullscreen 属性は、ブール属性です。指定されている場合、Document オブジェクトが iframe 要素の コンテンツナビゲーブル
内で初期化されるときに、「fullscreen」機能が任意の オリジン から使用できるようにすることを示します。これは、権限ポリシー属性を処理する アルゴリズムによって強制されます。[PERMISSIONSPOLICY]
ここでは、iframe
を使用して、ビデオサイトからプレイヤーを埋め込んでいます。allowfullscreen
属性は、プレイヤーがビデオをフルスクリーンで表示できるようにするために必要です。
< article >
< header >
< p >< img src = "/usericons/1627591962735" > < b > Fred Flintstone</ b ></ p >
< p >< a href = "/posts/3095182851" rel = bookmark > 12:44</ a > — < a href = "#acl-3095182851" > Private Post</ a ></ p >
</ header >
< p > Check out my new ride!</ p >
< iframe src = "https://video.example.com/embed?id=92469812" allowfullscreen ></ iframe >
</ article >
allow 属性および
allowfullscreen
属性は、iframe 要素の コンテンツナビゲーブル
内の機能にアクセスできるようにすることはできません。その要素の ノードドキュメント
が既にその機能の使用を許可されていない場合、これらの属性は機能しません。
Document オブジェクト
document がポリシー制御機能 feature を 使用することを許可されている
かどうかを判断するには、以下のステップを実行します:
document の ブラウジングコンテキスト が null の場合、false を返します。
document が 完全にアクティブ でない場合、false を返します。
機能がドキュメントで有効であり、オリジンに対して有効である かどうかを feature
、document 、および document の オリジン
で確認し、その結果が "有効" であれば、true を返します。
false を返します。
これらの属性は、コンテンツナビゲーブルのアクティブドキュメントにおける権限ポリシーにのみ影響を与えるため、allowおよびallowfullscreen属性は、iframeのコンテンツナビゲーブルがナビゲートされたときにのみ効果を発揮します。これらの属性を追加または削除しても、既に読み込まれたドキュメントには影響を与えません。
iframe要素は、埋め込みコンテンツが特定の寸法を持つ場合(例:広告ユニットが明確に定義された寸法を持つ場合)に、寸法属性をサポートしています。
iframe要素には、フォールバックコンテンツが含まれることはなく、指定された初期コンテンツが正常に使用されるかどうかにかかわらず、常に新しい子ナビゲーブルを作成します。
referrerpolicy属性は、リファラーポリシー属性です。その目的は、リファラーポリシーを設定することで、iframe属性の処理時に使用されます。[REFERRERPOLICY]
loading属性は、遅延読み込み属性です。その目的は、ビューポート外にあるiframe要素の読み込みポリシーを示すことです。
loading属性の状態がEager状態に変更されたとき、ユーザーエージェントは次のステップを実行する必要があります:
resumptionStepsを、iframe要素の遅延読み込み再開ステップとします。
もしresumptionStepsがnullである場合は、何も返しません。
iframeの遅延読み込み再開ステップをnullに設定します。
resumptionStepsを実行します。
iframe要素の子孫は何も表しません。(iframe要素をサポートしていないレガシーユーザーエージェントでは、コンテンツがマークアップとして解析され、フォールバックコンテンツとして機能する可能性があります。)
HTMLパーサーは、iframe要素内のマークアップをテキストとして扱います。
すべての現在のエンジンでサポートされています。
src、name、sandbox、およびallowIDL属性は、それぞれのコンテンツ属性と同名のコンテンツ属性を反映しなければなりません。
すべての現在のエンジンでサポートされています。
srcdocのゲッターステップは次のとおりです:
attributeを、名前空間およびローカル名で属性を取得する結果とします。null、srcdocのローカル名、およびthisを指定します。
もしattributeがnullであれば、空の文字列を返します。
attributeの値を返します。
srcdocのセッターステップは次のとおりです:
compliantStringを、TrustedHTML、thisの関連するグローバルオブジェクト、与えられた値、"HTMLIFrameElement srcdoc"、および"script"を指定して、信頼されたタイプの準拠文字列を取得するアルゴリズムを呼び出す結果とします。
サポートされているトークンは、sandboxのDOMTokenListに対して定義された許可された値と、ユーザーエージェントがサポートしている値です。
allowFullscreenIDL属性は、同名のコンテンツ属性を反映しなければなりません。
HTMLIFrameElement/referrerPolicy
すべての現在のエンジンでサポートされています。
referrerPolicyIDL属性は、同名のコンテンツ属性を反映しなければならず、既知の値のみに制限されます。
loadingIDL属性は、同名のコンテンツ属性を反映しなければならず、既知の値のみに制限されます。
HTMLIFrameElement/contentDocument
すべての現在のエンジンでサポートされています。
contentDocumentゲッターステップは、thisのコンテンツドキュメントを返すことです。
HTMLIFrameElement/contentWindow
すべての現在のエンジンでサポートされています。
contentWindowゲッターステップは、thisのコンテンツウィンドウを返すことです。
ここでは、iframeを使用して広告仲介業者から広告を表示するページの例を示します:
< iframe src = "https://ads.example.com/?customerid=923513721&format=banner"
width = "468" height = "60" ></ iframe >
embed要素すべての最新エンジンでサポートされています。
すべての最新エンジンでサポートされています。
src — リソースのアドレス
type — 埋め込まれたリソースのタイプ
width — 水平方向の寸法
height — 垂直方向の寸法
[Exposed =Window ]
interface HTMLEmbedElement : HTMLElement {
[HTMLConstructor ] constructor ();
[CEReactions ] attribute USVString src ;
[CEReactions ] attribute DOMString type ;
[CEReactions ] attribute DOMString width ;
[CEReactions ] attribute DOMString height ;
Document ? getSVGDocument ();
// 古いメンバーも持つ
};
embed要素は、外部アプリケーションやインタラクティブコンテンツの統合ポイントを提供します。
src属性は、埋め込まれるリソースのURLを指定します。この属性が存在する場合、有効な空でないURL(スペースで囲まれている可能性あり)を含めなければなりません。
itemprop属性がembed要素に指定されている場合、src属性も指定されなければなりません。
type属性が存在する場合、プラグインを選択するために使用されるMIMEタイプを指定します。この値は有効なMIMEタイプ文字列でなければなりません。type属性とsrc属性が共に存在する場合、type属性は、src属性によって指定されたリソースの明示的なコンテンツタイプメタデータと同じタイプを指定しなければなりません。
以下のいずれかの条件が発生している場合、その要素に対してインスタンス化されたプラグインは削除され、embed要素は何も表しません:
要素にメディア要素の先祖がある。
要素に、表示されていないフォールバックコンテンツを持つobject要素の先祖がある。
embed要素は、以下の条件がすべて同時に満たされるときに潜在的にアクティブであると言われます:
要素のsrc属性が存在しないか、その値が空文字列ではない。
要素がメディア要素の子孫ではない。
要素が、表示されていないフォールバックコンテンツを持つobject要素の子孫ではない。
要素がレンダリングされている、または最後にイベントループがステップ1に達した時にレンダリングされていた。
embed要素が潜在的にアクティブではなかったが、潜在的にアクティブになる時、または潜在的にアクティブな状態を維持し続け、src属性が設定され、変更され、または削除された場合、またはtype属性が設定され、変更され、または削除された場合、ユーザーエージェントは、その要素に対して要素タスクをキューに追加し、その要素のために
embed要素のセットアップ手順を実行する必要があります。
embed要素のセットアップ手順は、指定されたembed要素elementに対して以下のように行われます:
他のタスクがその後、elementのためにembed要素のセットアップ手順を実行するためにキューに追加された場合は、終了します。
elementにsrc属性が設定されている場合、次の手順を実行します:
urlを、elementのsrc属性の値をelementのノードドキュメントに対して相対的にURLのエンコード解析を行うことによって得られる結果にします。
urlが失敗であれば、終了します。
requestを新しいリクエストとし、そのURLをurl、クライアントをelementのノードドキュメントの関連設定オブジェクト、宛先を「embed」、資格情報モードを「include」、モードを「navigate」、発起人タイプを「embed」、URL資格情報フラグを設定したものにします。
requestをフェッチし、レスポンスの処理を、レスポンス responseに対して以下の手順を設定して実行します:
他のタスクがその後、elementのためにembed要素のセットアップ手順を実行するためにキューに追加された場合は、終了します。
typeをelementとresponseに基づいてコンテンツのタイプを決定する結果にします。
typeに応じてスイッチします:
elementに対してプラグインを表示しないことを行います。
elementのコンテンツナビゲーブルがnullであれば、elementのために新しい子ナビゲーブルを作成します。
elementのコンテンツナビゲーブルを、responseのURLに、elementのノードドキュメントを使用して、レスポンスをresponseに設定し、履歴処理を「replace」に設定してナビゲートします。
elementのsrc属性は、コンテンツナビゲーブルが他の場所にさらにナビゲートされた場合には更新されません。
elementは今やそのコンテンツナビゲーブルを表しています。
リソースのフェッチは、elementのノードドキュメントのロードイベントを遅らせる必要があります。
それ以外の場合、elementに対してプラグインを表示しないことを行います。
コンテンツのタイプを、指定されたembed要素elementとレスポンスresponseに基づいて決定するには、次の手順を実行します:
responseのパスコンポーネントがURLに含まれており、それがプラグインがサポートするパターンと一致する場合、そのプラグインが処理できるタイプを返します。
例えば、あるプラグインは、パスコンポーネントが「.swf」で終わるURLを処理できると主張するかもしれません。
responseに明示的なコンテンツタイプメタデータがあり、その値がプラグインがサポートするタイプである場合、その値を返します。
nullを返します。
上記のアルゴリズムが、responseにokステータスがない場合でも、responseを許可するのは意図的です。これにより、サーバーはエラーレスポンス(例:HTTP 500内部サーバーエラーコード)を持っていても、プラグインデータを返すことができます。
embed要素に対してプラグインを表示しない方法は以下の通りです:
elementに対して子ナビゲーブルを破壊します。
elementに対してプラグインが見つからなかったことを示すインジケータを表示し、その内容をelementとして表示します。
elementは何も表さなくなります。
embed要素にはフォールバックコンテンツがなく、その子孫は無視されます。
embed要素が潜在的にアクティブでなくなると、その要素に対してインスタンス化されたプラグインはアンロードされなければなりません。
embed要素はロードイベントを遅らせる可能性があります。
srcおよびtypeというIDL属性は、それぞれ同名のコンテンツ属性を反映しなければなりません。
object 要素すべての最新エンジンでサポートされています。
すべての最新エンジンでサポートされています。
data — リソースのアドレス
type — 埋め込まれたリソースのタイプ
name — コンテンツナビゲーブルの名前
form — フォーム要素と関連付ける
width — 水平方向の寸法
height — 垂直方向の寸法
[Exposed =Window ]
interface HTMLObjectElement : HTMLElement {
[HTMLConstructor ] constructor ();
[CEReactions ] attribute USVString data ;
[CEReactions ] attribute DOMString type ;
[CEReactions ] attribute DOMString name ;
readonly attribute HTMLFormElement ? form ;
[CEReactions ] attribute DOMString width ;
[CEReactions ] attribute DOMString height ;
readonly attribute Document ? contentDocument ;
readonly attribute WindowProxy ? contentWindow ;
Document ? getSVGDocument ();
readonly attribute boolean willValidate ;
readonly attribute ValidityState validity ;
readonly attribute DOMString validationMessage ;
boolean checkValidity ();
boolean reportValidity ();
undefined setCustomValidity (DOMString error );
// 古いメンバーも持つ
};
object要素によってインスタンス化されたコンテンツのタイプに応じて、このノードは他のインターフェースもサポートします。
object要素は、外部リソースを表すことができ、そのリソースのタイプに応じて、画像として扱われるか、子ナビゲーブルとして扱われます。
data属性は、リソースのURLを指定します。この属性は必須であり、有効な空でない
URL(スペースで囲まれている可能性あり)を含まなければなりません。
type属性が存在する場合、リソースのタイプを指定します。存在する場合、この属性は有効な MIME タイプ文字列でなければなりません。
name属性が存在する場合、有効なナビゲーブルターゲット名でなければなりません。指定された値は、要素のコンテンツナビゲーブルの名前に使用され、適用可能であれば、要素のコンテンツナビゲーブルが作成されるときに存在します。
次のいずれかの条件が発生するとき:
object要素のいずれかが、そのフォールバックコンテンツを表示するかどうか変わるとき、
classid属性が設定、変更、または削除されるとき、
classid属性が存在しない場合、およびそのdata属性が設定、変更、または削除されるとき、
classid属性もdata属性も存在せず、type属性が設定、変更、または削除されるとき、
...ユーザーエージェントは、object要素に対して、次の手順を実行してその要素が何を表すかを(再)決定するために要素タスクをキューに追加する必要があります。このタスクがキューに追加されるか、または実行中である場合は、要素のノードドキュメントのロードイベントを遅らせる必要があります。
ユーザーがこのobject要素の通常の動作の代わりにフォールバックコンテンツを表示するように指定した場合、以下のフォールバックとラベル付けされたステップにジャンプします。
例えば、ユーザーがそのコンテンツがよりアクセスしやすい形式を使用しているために、要素のフォールバックコンテンツの表示を要求することがあります。
要素に先祖となるメディア要素がある場合、または先祖となるobject要素があり、それがフォールバックコンテンツを表示していない場合、または要素が文書内にあり、そのブラウジングコンテキストがnullでない場合、あるいは要素のノード文書が完全にアクティブでない場合、または要素がオープン要素のスタックの中にまだある場合、または要素がレンダリングされていない場合は、以下のフォールバックとラベル付けされたステップにジャンプします。
もしdata属性が存在し、その値が空でない場合:
もしtype属性が存在し、その値がユーザーエージェントがサポートしていないタイプである場合、ユーザーエージェントは実際のタイプを調べるためにコンテンツを取得することなく、以下のフォールバックとラベル付けされたステップにジャンプできます。
urlを、data属性の値と要素のノード文書に基づいて、URLをエンコーディング解析することで得られた結果とします。
もしurlが失敗した場合、イベントをerrorという名前で要素に対して発生させ、以下のフォールバックとラベル付けされたステップにジャンプします。
requestを新しいリクエストとし、そのurlをURLとし、クライアントは要素のノード文書の関連設定オブジェクトとし、デスティネーションは"object"とし、認証モードは"include"とし、モードは"navigate"とし、イニシエータータイプは"object"とし、URLクレデンシャルを使用するフラグが設定されているとします。
リクエストをフェッチします。
リソースの取得は、リソースが取得された後にネットワーキングタスクソースによってキューに入れられたタスクが実行されるまで、要素のノードドキュメントのロードイベントを遅延させる必要があります。
リソースがまだ利用できない場合(例:リソースがキャッシュにないため、リソースのロードにネットワーク上でリクエストが必要である場合)、以下のフォールバックとラベル付けされたステップにジャンプします。リソースが利用可能になるとネットワーキングタスクソースによってキューに入れられるタスクは、このステップからアルゴリズムを再開する必要があります。リソースは断続的にロードでき、ユーザーエージェントは十分なデータが取得されたときにリソースを「利用可能」と見なすオプションがあります。
ロードが失敗した場合(例:HTTP 404エラー、DNSエラーがあった場合)、イベントをerrorという名前で要素に対して発生させ、その後、以下のフォールバックとラベル付けされたステップにジャンプします。
次の手順でリソースタイプを決定します:
リソースタイプを不明にします。
ユーザーエージェントがこのリソースのContent-Typeヘッダーを厳密に遵守するように設定されている場合、およびリソースに関連するContent-Typeメタデータがある場合、リソースタイプをリソースのContent-Typeメタデータに指定されているタイプとし、以下のハンドラーとラベル付けされたステップにジャンプします。
これにより、サイトが特定のタイプを使用してリソースを埋め込もうとしているが、リモートサイトがそれを上書きし、代わりにユーザーエージェントに異なるタイプのコンテンツを提供し、異なるセキュリティ特性を持つ可能性があるという脆弱性が生じる可能性があります。
次のリストから適切な一連の手順を実行します:
バイナリをfalseに設定します。
リソースのContent-Typeメタデータに指定されているタイプが"text/plain"であり、リソースに対してテキストまたはバイナリかを区別するルールを適用した結果、リソースがtext/plainでない場合、バイナリをtrueに設定します。
リソースのContent-Typeメタデータに指定されているタイプが"application/octet-stream"である場合、バイナリをtrueに設定します。
もしバイナリがfalseであれば、リソースタイプをリソースのContent-Typeメタデータに指定されているタイプにし、以下のハンドラーとラベル付けされたステップにジャンプします。
もしtype属性が存在し、かつその値がapplication/octet-streamでない場合、以下の手順を実行します:
もしその属性の値が、"image/"で始まり、かつリソースタイプが不明の場合、リソースタイプをtype属性に指定されているタイプとします。
以下のハンドラーとラベル付けされたステップにジャンプします。
もしtype属性が存在する場合、仮のタイプをtype属性に指定されているタイプとします。
そうでない場合、仮のタイプをリソースの計算されたタイプとします。
もし仮のタイプがapplication/octet-streamでない場合、リソースタイプを仮のタイプとし、以下のハンドラーとラベル付けされたステップにジャンプします。
指定されたリソースのURLパーサーアルゴリズムを適用した結果(リダイレクト後)として、URLレコードが、パスコンポーネントと一致するパターンを持つ場合、リソースタイプをそのプラグインが処理できるタイプとします。
例えば、プラグインが".swf"で終わるパスコンポーネントを持つリソースを処理できると指定する場合があります。
このステップが完了するか、上記のサブステップのいずれかが次のステップに直接ジャンプすることで、リソースタイプが依然として不明である可能性があります。いずれの場合でも、次のステップでフォールバックがトリガーされます。
ハンドラー: 次のケースのうち最初に一致するものとしてコンテンツを処理します:
XML MIMEタイプである場合、またはリソースタイプが"image/"で始まらない場合
もしobject要素のコンテンツナビゲーブルがnullである場合、その要素のために新しい子ナビゲーブルを作成します。
レスポンスを、フェッチから得られるレスポンスのURLとします。
もしレスポンスのURLがabout:blankと一致しない場合、要素の履歴処理を"置換"に設定して、要素のノード文書を使用してナビゲートします。
要素のコンテンツナビゲーブルが他の場所にさらにナビゲートされた場合でも、要素のdata属性は更新されません。
object要素はそのコンテンツナビゲーブルを表します。
image/"で始まり、画像サポートが無効化されていない場合object要素に対して子ナビゲーブルを破壊します。
画像のスニッフィングルールを適用して画像のタイプを決定します。
object要素は指定された画像を表します。
もし画像が不正であるか、またはサポートされていないフォーマットであるためにレンダリングできない場合は、以下のフォールバックとラベル付けされたステップにジャンプします。
指定されたリソースタイプはサポートされていません。以下のフォールバックとラベル付けされたステップにジャンプします。
前のステップがリソースタイプ不明のまま終了した場合、これはトリガーされるケースです。
要素の内容はobject要素が表すものの一部ではありません。
もしobject要素がそのコンテンツナビゲーブルを表していない場合、リソースが完全にロードされた後で、DOM操作タスクソースに要素タスクをキューし、要素に対してloadという名前のイベントを発生させます。
もし要素がそのコンテンツナビゲーブルを表している場合、作成されたDocumentが完全にロードが完了したときに同様のタスクがキューに入れられます。
戻ります。
フォールバック: object要素はその子要素を表します。これは要素のフォールバックコンテンツです。要素に対して子ナビゲーブルを破壊します。
上述のアルゴリズムにより、object要素の内容は、参照されたリソースが表示できない場合(例:404エラーが発生した場合)にのみ使用されるフォールバックコンテンツとして機能します。これにより、複数のobject要素を入れ子にして、それぞれ異なる能力を持つユーザーエージェントをターゲットにすることができ、ユーザーエージェントはサポートする最初のものを選択します。
object要素はロードイベントを遅延させる可能性があります。
form属性は、object要素をフォームの所有者と明示的に関連付けるために使用されます。
すべての現在のエンジンでサポートされています。
すべての現在のエンジンでサポートされています。
すべての現在のエンジンでサポートされています。
IDL属性data、type、およびnameは、それぞれ同名のコンテンツ属性を反映する必要があります。
HTMLObjectElement/contentDocument
すべての現在のエンジンでサポートされています。
contentDocumentゲッターステップは、thisのコンテンツドキュメントを返すことです。
HTMLObjectElement/contentWindow
すべての現在のエンジンでサポートされています。
contentWindowゲッターステップは、thisのコンテンツウィンドウを返すことです。
willValidate、validity、validationMessage属性、およびcheckValidity()、reportValidity()、setCustomValidity()メソッドは、制約検証APIの一部です。formIDL属性は、要素のフォームAPIの一部です。
この例では、object要素を使用してHTMLページが別のページに埋め込まれています。
< figure >
< object data = "clock.html" ></ object >
< figcaption > My HTML Clock</ figcaption >
</ figure >
video要素すべての現在のエンジンでサポートされています。
すべての現在のエンジンでサポートされています。
controls属性を持つ場合:
インタラクティブコンテンツ
src属性を持つ場合:track要素、その後透明、ただし、メディア要素の子孫は含まれない。src属性を持たない場合:
ゼロまたはそれ以上のsource要素、その後ゼロまたはそれ以上のtrack要素、その後透明、ただし、メディア要素の子孫は含まれない。src — リソースのアドレスcrossorigin —
クロスオリジンリクエストの処理方法poster —
ビデオ再生前に表示するポスターフレームpreload — メディアリソースが必要とするバッファリングのヒントautoplay —
ページが読み込まれたときに自動的にメディアリソースを開始できることを示唆するplaysinline —
ユーザーエージェントに、ビデオコンテンツを要素の再生エリア内に表示することを促すloop — メディアリソースをループ再生するかどうかmuted — メディアリソースをデフォルトでミュートするかどうかcontrols —
ユーザーエージェントコントロールを表示するかどうかwidth — 水平次元height — 垂直次元[Exposed =Window ]
interface HTMLVideoElement : HTMLMediaElement {
[HTMLConstructor ] constructor ();
[CEReactions ] attribute unsigned long width ;
[CEReactions ] attribute unsigned long height ;
readonly attribute unsigned long videoWidth ;
readonly attribute unsigned long videoHeight ;
[CEReactions ] attribute USVString poster ;
[CEReactions ] attribute boolean playsInline ;
};
video要素は、ビデオや映画、字幕付きのオーディオファイルを再生するために使用されます。
video要素内にコンテンツを提供することができますが、ユーザーエージェントはこのコンテンツをユーザーに表示しないようにすべきです。このコンテンツは、video要素をサポートしていない古いウェブブラウザ向けであり、そのような古いブラウザのユーザーに対してビデオコンテンツにアクセスする方法を知らせるためにテキストが表示されます。
特に、このコンテンツはアクセシビリティの問題を解決することを目的としているわけではありません。視覚障害者、聴覚障害者、そしてその他の身体的または認知的障害を持つ人々にビデオコンテンツをアクセス可能にするために、さまざまな機能が利用可能です。キャプションは、ビデオストリームに埋め込まれるか、track要素を使用して外部ファイルとして提供できます。手話トラックはビデオストリームに埋め込むことができます。音声説明はビデオストリームに埋め込むか、WebVTTファイルを使用してテキスト形式で提供し、ユーザーエージェントによって音声合成されることもあります。WebVTTは、チャプタータイトルの提供にも使用できます。メディア要素をまったく使用したくないユーザー向けに、video要素の近くの文中でリンクを使用して、トランスクリプトやその他のテキスト代替を提供することもできます。[WEBVTT]
video要素は、メディア要素であり、そのメディアデータは表面的にはビデオデータであり、関連するオーディオデータが含まれる可能性があります。
src、crossorigin、preload、autoplay、loop、muted、controls属性は、すべてのメディア要素に共通の属性です。
poster属性は、ユーザーエージェントがビデオデータが利用できない間に表示できる画像ファイルのURLを指定します。この属性が存在する場合、その内容は有効な非空のURLで、スペースで囲まれている可能性があります。
指定されたリソースが使用される場合、要素が作成されるとき、またはposter属性が設定、変更、または削除されたときに、ユーザーエージェントは次の手順を実行して、要素のポスターフレームを決定しなければなりません(要素のポスターフラグの値に関係なく)。
このvideo要素に対して実行中のインスタンスが存在する場合、そのインスタンスを中断し、ポスターフレームを変更せずに終了します。
属性の値を相対して、URLのエンコーディングと解析の結果をurlとします。要素のノード文書に相対して。
もしurlが失敗した場合、終了します。ポスターフレームはありません。
requestを新しいリクエストとし、URLをurl、クライアントを要素のノード文書の関連する設定オブジェクト、宛先をimage、発信元タイプをvideo、資格情報モードをinclude、URL資格情報フラグを設定します。
リクエストをフェッチします。これにより、要素のロードイベントを遅延させる必要があります。要素のノード文書の。
poster属性で指定された画像、つまりポスターフレームは、ビデオの代表的なフレーム(通常は最初の非空白のフレーム)であり、ビデオの概要をユーザーに伝えることを目的としています。
playsinline属性はブール属性です。この属性が存在する場合、それはユーザーエージェントに対するヒントとして機能し、ビデオをデフォルトでドキュメント内で「インライン」で表示し、要素の再生エリアに制約され、フルスクリーンや独立したリサイズ可能なウィンドウで表示されることはありません。
playsinline属性が存在しないからといって、ビデオがデフォルトでフルスクリーンで表示されることを意味するわけではありません。実際、ほとんどのユーザーエージェントはデフォルトでビデオをすべてインラインで再生することを選択しており、そのようなユーザーエージェントではplaysinline属性には何の効果もありません。
video
要素は、以下のリストで最初に一致する条件に対して、指定された内容を表します。
readyState 属性が HAVE_NOTHING または
HAVE_METADATA
であり、ビデオデータがまだ全く取得されていない場合、または要素の readyState
属性が以降のいずれかの値であるが、メディアリソース にビデオチャンネルがない場合)
video 要素は、存在する場合は ポスターフレーム を表し、それ以外の場合は 透明な黒 を表し、自然な寸法 はありません。
video 要素が 一時停止中 で、現在の再生位置
がビデオの最初のフレームであり、要素の ポスターフラグを表示
が設定されている場合
video 要素は、存在する場合は ポスターフレーム を表し、それ以外の場合はビデオの最初のフレームを表します。
video 要素が 一時停止中 で、現在の再生位置
に対応するビデオのフレームが利用できない場合(例えば、ビデオがシーク中またはバッファリング中である場合)
video 要素が 再生中である可能性 も 一時停止中 でもない場合(例えば、シーク中または停止中の場合)
video
要素は、最後にレンダリングされたビデオのフレームを表します。
video 要素が 一時停止中 の場合
video 要素は、現在の再生位置
に対応するビデオのフレームを表します。
video
要素にビデオチャンネルがあり、再生中である可能性がある場合)
video 要素は、連続的に増加する 現在の位置 のフレームを表します。現在の再生位置
が変わり、最後にレンダリングされたフレームがビデオの 現在の再生位置 に対応しなくなった場合、新しいフレームがレンダリングされなければなりません。
ビデオのフレームは、選択されたビデオトラック から取得される必要があります。イベントループ が最後に ステップ1 に到達したときに選択されたトラックです。
ビデオストリーム内の特定の再生位置に対応するフレームは、ビデオストリームの形式によって定義されます。
video 要素は、テキストトラックのキュー をも 表します。テキストトラックキューアクティブフラグ が設定され、テキストトラック が 表示モード になっている場合、そして メディアリソース のオーディオも現在の再生位置において表します。
メディアリソース に関連付けられたオーディオは、再生される場合、現在の再生位置 に同期して再生される必要があります。ユーザーエージェントは、イベントループ が最後にステップ1に到達したときに有効化されたオーディオトラックからオーディオを再生しなければなりません。
さらに、ユーザーエージェントは、ビデオ上または要素の再生エリアの他の領域にテキストやアイコンを重ねたり、その他の適切な方法で、"バッファリング中"、"ビデオがロードされていません"、"エラー"、またはより詳細な情報などのメッセージをユーザーに提供することができます。
ビデオをレンダリングできないユーザーエージェントは、代わりに要素を外部のビデオ再生ユーティリティへのリンクやビデオデータ自体 を表すようにすることができます。
video 要素の メディアリソース にビデオチャンネルがある場合、要素は、ペイントソース を提供します。このソースの幅は メディアリソース の自然幅、高さは メディアリソース の 自然高さ であり、その見た目は、利用可能な場合は 現在の再生位置
に対応するビデオのフレームの外観であり、そうでない場合(例えば、ビデオがシーク中またはバッファリング中である場合)、以前の外観であり、それも利用できない場合(例えば、ビデオが最初のフレームをロード中であるため)には、黒である場合があります。
video.videoWidth
すべての現在のエンジンでサポートされています。
video.videoHeight
すべての現在のエンジンでサポートされています。
これらの属性は、ビデオの自然な寸法を返すか、寸法が不明な場合は0を返します。
自然な幅と自然な高さは、メディアリソースの寸法を、リソースの寸法、アスペクト比、クリンアパーチャ、解像度などを考慮した後のCSS ピクセルでの寸法として定義されます。アナモルフィックフォーマットがビデオデータの寸法にアスペクト比をどのように適用するかを定義していない場合、ユーザーエージェントは、1つの寸法を増加させ、もう1つの寸法を変更せずに比率を適用する必要があります。
videoWidth
IDL属性は、ビデオの自然な幅をCSS
ピクセルで返す必要があります。videoHeight IDL属性は、ビデオの自然な高さをCSS
ピクセルで返す必要があります。要素のreadyState属性がHAVE_NOTHINGの場合、属性は0を返す必要があります。
ビデオの自然な幅または自然な高さが変更された場合(たとえば、選択されたビデオトラックが変更されたため)、要素のreadyState属性がHAVE_NOTHINGでない場合、ユーザーエージェントはメディア要素タスクをキューに入れる必要があり、イベントを発火し、resizeという名前のイベントをメディア要素で発生させる必要があります。
特定のスタイルルールがない場合、ビデオコンテンツは要素の再生エリア内で最大サイズで中央に表示され、ビデオコンテンツのアスペクト比が維持されるようにレンダリングされるべきです。したがって、再生エリアのアスペクト比がビデオのアスペクト比と一致しない場合、ビデオはレターボックスまたはピラーボックス形式で表示されます。要素の再生エリアのビデオを含まない部分は、何も表さないことを意味します。
CSSを実装しているユーザーエージェントでは、上記の要件は、レンダリングセクションで提案されているスタイルルールを使用することで実装できます。
自然な幅は、video要素の再生エリアのポスターフレームが利用可能であり、要素が現在そのポスターフレームを表している場合、そのポスターフレームの自然な幅です。そうでない場合は、ビデオリソースの自然な幅です。ビデオリソースが利用可能でない場合、自然な幅は失われます。
自然な高さは、video要素の再生エリアのポスターフレームが利用可能であり、要素が現在そのポスターフレームを表している場合、そのポスターフレームの自然な高さです。そうでない場合は、ビデオリソースの自然な高さです。ビデオリソースが利用可能でない場合、自然な高さは失われます。
デフォルトのオブジェクトサイズは、幅300 CSSピクセル、高さ150 CSSピクセルです。[CSSIMAGES]
ユーザーエージェントは、クローズドキャプション、音声説明トラック、およびビデオストリームに関連するその他の追加データの表示を有効または無効にするコントロールを提供すべきですが、これらの機能はページの通常のレンダリングを妨げないようにすべきです。
ユーザーエージェントは、ユーザーにより適した方法でビデオコンテンツを表示できるようにするかもしれません。たとえば、フルスクリーンや独立したサイズ変更可能なウィンドウで表示することができます。ユーザーエージェントは、ビデオの再生時にデフォルトでこのような表示モードをトリガーすることもできますが、playsinline属性が指定されている場合はそうすべきではありません。他のユーザーインターフェイス機能と同様に、これを有効にするコントロールは、ユーザーエージェントがユーザーインターフェイスをユーザーに公開している場合を除き、ページの通常のレンダリングを妨げるべきではありません。ただし、このような独立した表示モードでは、controls属性がない場合でも、ユーザーエージェントは完全なユーザーインターフェイスを表示することができます。
ユーザーエージェントは、ビデオ再生中にスクリーンセーバーを無効にするなど、ユーザーの体験を妨げる可能性のあるシステム機能にビデオ再生が影響を与えることを許可する場合があります。
poster
IDL属性は、posterコンテンツ属性を反映する必要があります。
playsInline IDL属性は、playsinlineコンテンツ属性を反映する必要があります。
次の例は、ビデオが正しく再生されなかった場合を検出する方法を示しています。
< script >
function failed( e) {
// ビデオの再生が失敗した場合 - なぜかを示すメッセージを表示する
switch ( e. target. error. code) {
case e. target. error. MEDIA_ERR_ABORTED:
alert( 'ビデオの再生が中止されました。' );
break ;
case e. target. error. MEDIA_ERR_NETWORK:
alert( 'ネットワークエラーにより、ビデオのダウンロードが途中で失敗しました。' );
break ;
case e. target. error. MEDIA_ERR_DECODE:
alert( 'ビデオの再生が、破損問題やブラウザがサポートしていない機能を使用したため中止されました。' );
break ;
case e. target. error. MEDIA_ERR_SRC_NOT_SUPPORTED:
alert( 'サーバーまたはネットワークが失敗したか、形式がサポートされていないため、ビデオをロードできませんでした。' );
break ;
default :
alert( '不明なエラーが発生しました。' );
break ;
}
}
</ script >
< p >< video src = "tgif.vid" autoplay controls onerror = "failed(event)" ></ video ></ p >
< p >< a href = "tgif.vid" > ビデオファイルをダウンロード</ a > .</ p >
audio
要素すべての現在のエンジンでサポートされています。
すべての現在のエンジンでサポートされています。
controls属性がある場合:
インタラクティブコンテンツ.
controls属性がある場合:
パルパブルコンテンツ.
src属性がある場合:
0個以上のtrack要素、その後
透過的だが、メディア要素の子孫は含まない。
src属性がない場合: 0個以上の
source要素、その後
0個以上のtrack要素、その後
透過的だが、メディア要素の子孫は含まない。
src — リソースのアドレス
crossorigin —
クロスオリジンリクエストの処理方法
preload — メディアリソースが必要とするバッファリングの量を示唆します
autoplay —
ページが読み込まれたときにメディアリソースを自動的に再生できることを示唆します
loop — メディアリソースをループ再生するかどうか
muted — デフォルトでメディアリソースをミュートするかどうか
controls —
ユーザーエージェントのコントロールを表示する
[Exposed =Window ,
LegacyFactoryFunction =Audio (optional DOMString src )]
interface HTMLAudioElement : HTMLMediaElement {
[HTMLConstructor ] constructor ();
};
audio要素は、音声またはオーディオストリームを表します。
audio要素の中にコンテンツを提供することができます。ユーザーエージェントはこのコンテンツをユーザーに表示すべきではありません。これは、audioをサポートしない古いウェブブラウザ向けであり、これらの古いブラウザのユーザーに音声コンテンツにアクセスする方法を知らせるためのテキストを表示することを目的としています。
特に、このコンテンツはアクセシビリティの問題に対処するためのものではありません。聴覚障害者やその他の身体的・認知的障害を持つ人々のために、音声コンテンツをアクセシブルにするためのさまざまな機能が利用可能です。キャプションや手話ビデオが利用可能な場合、video要素を使用して音声を再生し、ユーザーが視覚的な代替手段を有効にできるようにすることができます。章のタイトルをtrack要素とWebVTTファイルを使用して提供し、ナビゲーションを支援することができます。また、もちろん、トランスクリプトやその他のテキストによる代替手段をaudio要素の近くの文章で単にリンクすることで提供することができます。[WEBVTT]
audio要素は、メディア要素であり、そのメディアデータは表向きにはオーディオデータです。
src、crossorigin、preload、autoplay、loop、muted、およびcontrols属性は、すべてのメディア要素に共通する属性です。
audio = new Audio([ url ])
すべての現在のエンジンでサポートされています。
HTMLAudioElementオブジェクトを作成するためのレガシーファクトリ関数が提供されています(DOMからのファクトリメソッドに加えて、例えばcreateElement()などです)。Audio(src)。レガシーファクトリ関数が呼び出された場合、次の手順を実行する必要があります:
documentを現在のグローバルオブジェクトの関連するDocumentとする。
もしsrcが与えられた場合、属性値を設定するaudioのために"src"とsrcを用いる。(これにより、オブジェクトのリソース選択アルゴリズムを返す前にユーザーエージェントが呼び出すことを引き起こす)
audioを返す。
track要素すべての現在のエンジンでサポートされています。
すべての現在のエンジンでサポートされています。
kind — テキストトラックの種類
src — リソースのアドレス
srclang — テキストトラックの言語
label — ユーザーに見えるラベル
default — 他のテキストトラックがより適切でない場合にトラックを有効にする
[Exposed =Window ]
interface HTMLTrackElement : HTMLElement {
[HTMLConstructor ] constructor ();
[CEReactions ] attribute DOMString kind ;
[CEReactions ] attribute USVString src ;
[CEReactions ] attribute DOMString srclang ;
[CEReactions ] attribute DOMString label ;
[CEReactions ] attribute boolean default ;
const unsigned short NONE = 0;
const unsigned short LOADING = 1;
const unsigned short LOADED = 2;
const unsigned short ERROR = 3;
readonly attribute unsigned short readyState ;
readonly attribute TextTrack track ;
};
track要素は、メディア要素に対して、外部の明示的なタイミング付きテキストトラックを指定するために使用されます。この要素自体は何も表しません。
kind属性は、列挙属性であり、次のキーワードと状態を持ちます:
| キーワード | 状態 | 簡単な説明 |
|---|---|---|
subtitles
| 字幕 | 音声が利用可能であるが理解できない場合(例:ユーザーがメディアリソースの音声トラックの言語を理解しない場合)に適した対話の文字起こしまたは翻訳。ビデオ上に重ねて表示されます。 |
captions
| キャプション | 音声が利用できないか、はっきり聞こえない場合に適した対話、効果音、関連する音楽の手がかり、およびその他の関連する音声情報の文字起こしまたは翻訳(例:音声がミュートされている場合や、周囲の騒音によってかき消されている場合、またはユーザーが聴覚障害者である場合)。ビデオ上に重ねて表示され、聴覚障害者向けに適切にラベル付けされます。 |
descriptions
| 説明 | ビデオコンポーネントが隠れている、利用できない、または使用できない場合に音声合成用に意図されたメディアリソースのビデオコンポーネントのテキスト説明(例:ユーザーが画面を見ないでアプリケーションを操作している場合や、ユーザーが盲目である場合)。音声として合成されます。 |
chapters
| チャプターメタデータ | スクリプトから使用されることを意図したトラック。ユーザーエージェントによって表示されません。 |
metadata
| メタデータ |
属性の欠落値デフォルトは字幕状態であり、無効値デフォルトはメタデータ状態です。
src属性は、テキストトラックデータのURLを指定します。値は有効な非空のURLであり、スペースで囲まれている場合があります。この属性は必須です。
この要素には関連付けられたトラックURL(文字列)があり、初期状態は空の文字列です。
要素のsrc属性が設定されたとき、次の手順を実行します:
trackURLを失敗に設定します。
valueを要素のsrc属性の値に設定します。
valueが空でない場合、trackURLを、要素のノードドキュメントに対してvalueを与えた場合のURLのエンコード、パース、およびシリアライズの結果に設定します。
要素のトラックURLをtrackURLに設定します。失敗でない場合はそれに設定し、それ以外の場合は空の文字列に設定します。
要素のトラックURLがWebVTTリソースを識別し、要素のkind属性がチャプターメタデータまたはメタデータ状態にない場合、WebVTTファイルはキューテキストを使用するWebVTTファイルである必要があります。[WEBVTT]
srclang属性は、テキストトラックデータの言語を指定します。値は有効なBCP
47言語タグである必要があります。この属性は、要素のkind属性が字幕状態にある場合は必須です。[BCP47]
要素がsrclang属性を持ち、その値が空でない場合、要素のトラック言語はその属性の値です。それ以外の場合、要素にはトラック言語がありません。
label属性は、ユーザーが読みやすいトラックのタイトルを指定します。このタイトルは、ユーザーエージェントがそのユーザーインターフェイスで字幕、キャプション、および音声説明トラックを一覧表示する際に使用されます。
label属性の値は、属性が存在する場合、空の文字列であってはなりません。また、同じメディア要素の子であり、kind属性が同じ状態にある、track要素が2つあってはなりません。また、それらのsrclang属性が欠落しているか、同じ言語を表す値を持ち、それらのlabel属性が再び両方とも欠落しているか、同じ値を持っている場合も同様です。
要素が空でないlabel属性を持っている場合、その要素のトラックラベルはその属性の値です。それ以外の場合、要素のトラックラベルは空の文字列です。
default属性はブール属性であり、指定されている場合、ユーザーの設定が他のトラックをより適切であると示さない限り、トラックが有効になることを示します。
メディア要素には、字幕状態またはキャプション状態にあるtrack要素の子が1つだけ存在し、そのdefault属性が指定されている必要があります。
メディア要素には、説明状態にあるtrack要素の子が1つだけ存在し、そのdefault属性が指定されている必要があります。
メディア要素には、チャプターメタデータ状態にあるtrack要素の子が1つだけ存在し、そのdefault属性が指定されている必要があります。
track要素のうち、kind属性がメタデータ状態にあり、default属性が指定されているものの数には制限がありません。
track.readyState
テキストトラックの準備状態を返します。これは、次のリストの数値で表されます:
track.NONE (0)
track.LOADING (1)
track.LOADED (2)
track.ERROR (3)
track.track
TextTrackオブジェクトを返します。これは、track要素のテキストトラックに対応します。
readyState属性は、track要素のテキストトラックのテキストトラックの準備状態に対応する数値値を返さなければなりません。
NONE(数値値0)
LOADING(数値値1)
LOADED(数値値2)
ERROR(数値値3)
trackIDL属性は、取得時に、track要素のテキストトラックに対応するTextTrackオブジェクトを返さなければなりません。
すべての現在のエンジンでサポートされています。
src, srclang, label, およびdefaultIDL属性は、同名のそれぞれのコンテンツ属性を反映しなければなりません。kindIDL属性は、同名のコンテンツ属性を反映しなければならず、既知の値のみに限定されます。
このビデオには、いくつかの言語の字幕があります:
< video src = "brave.webm" >
< track kind = subtitles src = brave.en.vtt srclang = en label = "English" >
< track kind = captions src = brave.en.hoh.vtt srclang = en label = "English for the Hard of Hearing" >
< track kind = subtitles src = brave.fr.vtt srclang = fr lang = fr label = "Français" >
< track kind = subtitles src = brave.de.vtt srclang = de lang = de label = "Deutsch" >
</ video >
(最後の2つのlang属性は、字幕自体の言語ではなく、label属性の言語を示します。字幕の言語は、srclang属性によって指定されます。)
HTMLMediaElementオブジェクト(この仕様ではaudioおよびvideo)は、単にメディア要素として知られています。
すべての現在のエンジンでサポートされています。
enum CanPlayTypeResult { "" /* empty string */, " maybe " , " probably " };
typedef (MediaStream or MediaSource or Blob ) MediaProvider ;
[Exposed =Window ]
interface HTMLMediaElement : HTMLElement {
// error state
readonly attribute MediaError ? error ;
// network state
[CEReactions ] attribute USVString src ;
attribute MediaProvider ? srcObject ;
readonly attribute USVString currentSrc ;
[CEReactions ] attribute DOMString ? crossOrigin ;
const unsigned short NETWORK_EMPTY = 0;
const unsigned short NETWORK_IDLE = 1;
const unsigned short NETWORK_LOADING = 2;
const unsigned short NETWORK_NO_SOURCE = 3;
readonly attribute unsigned short networkState ;
[CEReactions ] attribute DOMString preload ;
readonly attribute TimeRanges buffered ;
undefined load ();
CanPlayTypeResult canPlayType (DOMString type );
// ready state
const unsigned short HAVE_NOTHING = 0;
const unsigned short HAVE_METADATA = 1;
const unsigned short HAVE_CURRENT_DATA = 2;
const unsigned short HAVE_FUTURE_DATA = 3;
const unsigned short HAVE_ENOUGH_DATA = 4;
readonly attribute unsigned short readyState ;
readonly attribute boolean seeking ;
// playback state
attribute double currentTime ;
undefined fastSeek (double time );
readonly attribute unrestricted double duration ;
object getStartDate ();
readonly attribute boolean paused ;
attribute double defaultPlaybackRate ;
attribute double playbackRate ;
attribute boolean preservesPitch ;
readonly attribute TimeRanges played ;
readonly attribute TimeRanges seekable ;
readonly attribute boolean ended ;
[CEReactions ] attribute boolean autoplay ;
[CEReactions ] attribute boolean loop ;
Promise <undefined > play ();
undefined pause ();
// controls
[CEReactions ] attribute boolean controls ;
attribute double volume ;
attribute boolean muted ;
[CEReactions ] attribute boolean defaultMuted ;
// tracks
[SameObject ] readonly attribute AudioTrackList audioTracks ;
[SameObject ] readonly attribute VideoTrackList videoTracks ;
[SameObject ] readonly attribute TextTrackList textTracks ;
TextTrack addTextTrack (TextTrackKind kind , optional DOMString label = "", optional DOMString language = "");
};
メディア要素属性であるsrc、crossorigin、preload、autoplay、loop、muted、およびcontrolsは、すべてのメディア要素に適用されます。それらはこのセクションで定義されています。
メディア要素は、音声データや、映像および音声データをユーザーに提示するために使用されます。これは、このセクションでメディアデータと呼ばれています。このセクションは、音声または映像のためのメディア要素に等しく適用されるためです。 メディアリソースという用語は、完全な映像ファイルや音声ファイルなど、メディアデータ全体を指すために使用されます。
メディアリソースには、"none"、"multiple"、"rewritten"、またはオリジン"のいずれかのオリジンが関連付けられています。それは初期状態では"none"に設定されています。
メディアリソースには、複数の音声および映像トラックが含まれることがあります。メディア要素の目的のために、メディアリソースの映像データは、要素のvideoTracks属性によって現在選択されているトラック(もしあれば)のみであり、イベントループが最後にステップ1に到達したときに適用されます。また、メディアリソースの音声データは、要素のaudioTracks属性によって現在有効になっているすべてのトラック(もしあれば)をミキシングした結果です。
audio要素とvideo要素の両方が、音声および映像のために使用されることがあります。主な違いは、audio要素には視覚コンテンツ(映像やキャプションなど)の再生エリアがないのに対し、video要素にはそれがあるという点です。
各メディア要素には、一意のメディア要素イベントタスクソースがあります。
あるメディア要素elementと一連のステップstepsに対してメディア要素タスクをキューに入れるには、要素タスクをキューに入れ、elementとstepsを指定して、メディア要素イベントタスクソースにタスクをキューに入れます。
現在のすべてのエンジンでサポートされています。
media.error
現在のすべてのエンジンでサポートされています。
現在のエラー状態を表すMediaErrorオブジェクトを返します。
エラーがない場合はnullを返します。
すべてのメディア要素には関連するエラーステータスがあり、これは、要素が最後にリソース選択アルゴリズムを呼び出して以来、発生した最後のエラーを記録します。error属性は、取得時に、この最後のエラーに対して作成されたMediaErrorオブジェクトを返すか、エラーがない場合はnullを返します。
[Exposed =Window ]
interface MediaError {
const unsigned short MEDIA_ERR_ABORTED = 1;
const unsigned short MEDIA_ERR_NETWORK = 2;
const unsigned short MEDIA_ERR_DECODE = 3;
const unsigned short MEDIA_ERR_SRC_NOT_SUPPORTED = 4;
readonly attribute unsigned short code ;
readonly attribute DOMString message ;
};
media.error.code
現在のすべてのエンジンでサポートされています。
現在のエラーのエラーコードを以下のリストから返します。
media.error.message
現在のすべてのエンジンでサポートされています。
発生したエラー条件に関する特定の診断メッセージを返します。メッセージとメッセージ形式は、異なるユーザーエージェント間で一般的に一様ではありません。このようなメッセージが利用できない場合は、空の文字列が返されます。
すべてのMediaErrorオブジェクトには、文字列であるメッセージと、次のいずれかのコードがあります。
MEDIA_ERR_ABORTED(数値値 1)
MEDIA_ERR_NETWORK(数値値 2)
MEDIA_ERR_DECODE(数値値 3)
MEDIA_ERR_SRC_NOT_SUPPORTED(数値値 4)
src属性または割り当てられたメディアプロバイダーオブジェクトによって示されたメディアリソースが適切でありませんでした。
エラーコードが上記の値のいずれかであるMediaErrorを作成するには、指定されたエラーコードを持つ新しいMediaErrorオブジェクトを返します。このオブジェクトのコードは指定されたエラーコードであり、メッセージは、エラー条件の原因についてユーザーエージェントが提供できる詳細を含む文字列であるか、ユーザーエージェントがそのような詳細を提供できない場合は空の文字列です。このメッセージ文字列には、提供されたエラーコードを通じて既に利用可能な情報のみを含めるべきではありません。たとえば、コードを文字列形式に変換するだけではいけません。エラーコードで提供された情報以上の追加情報がない場合、メッセージは空の文字列に設定されなければなりません。
codeのgetterステップは、thisのコードを返します。
messageのgetterステップは、thisのメッセージを返します。
src コンテンツ属性は、メディア要素の表示するURLを指定します。この属性が存在する場合、有効な非空のURLが含まれている必要があります。
itemprop
属性がメディア要素に指定されている場合、src属性も指定されている必要があります。
crossorigin
コンテンツ属性は、メディア要素のCORS設定属性です。
メディア要素がsrc属性を持って作成された場合、ユーザーエージェントは直ちにそのメディア要素のリソース選択アルゴリズムを呼び出す必要があります。
メディア要素のsrc属性が設定または変更された場合、ユーザーエージェントはそのメディア要素のメディア要素の読み込みアルゴリズムを呼び出す必要があります。
(src 属性を削除しても、source
要素が存在していても、これを実行することはできません。)
すべての現在のエンジンでサポートされています。
src IDL属性は、メディア要素のコンテンツ属性と同じ名前を反映する必要があります。
すべての現在のエンジンでサポートされています。
crossOrigin IDL属性は、crossoriginコンテンツ属性を反映し、既知の値のみに制限される必要があります。
メディアプロバイダーオブジェクトは、メディアリソースをURLとは別に表現できるオブジェクトです。MediaStreamオブジェクト、MediaSourceオブジェクト、およびBlobオブジェクトは、すべてメディアプロバイダーオブジェクトです。
各メディア要素には、割り当てられたメディアプロバイダーオブジェクトを持つことができ、これはメディアプロバイダーオブジェクトです。メディア要素が作成されると、それには割り当てられたメディアプロバイダーオブジェクトはありません。
media.srcObject [ = source ]
1つのエンジンのみでサポートされています。
このプロパティを使用すると、メディア要素にメディアプロバイダーオブジェクトを割り当てることができます。
media.currentSrc
すべての現在のエンジンでサポートされています。
currentSrc
IDL属性は、最初に空の文字列に設定される必要があります。その値は、以下で定義されているリソース選択アルゴリズムによって変更されます。
srcObject
IDL属性は、取得時に要素の割り当てられたメディアプロバイダーオブジェクトを返す必要があり、存在しない場合はnullを返します。設定時には、要素の割り当てられたメディアプロバイダーオブジェクトを新しい値に設定し、その後、要素のメディア要素の読み込みアルゴリズムを呼び出す必要があります。
メディアリソースを指定する方法は3つあります:
srcObject
IDL属性、src
コンテンツ属性、およびsource要素です。IDL属性が優先され、次にコンテンツ属性、最後に要素が優先されます。
メディアリソースは、そのタイプ、具体的にはMIMEタイプで説明されることがあります。一部のケースではcodecsパラメータが付いていることもあります。(codecsパラメータが許可されるかどうかはMIMEタイプによります。)[RFC6381]
タイプは通常、いくつかの点で不完全な説明です。例えば、"video/mpeg"
はコンテナタイプしか示しておらず、"video/mp4; codecs="avc1.42E01E, mp4a.40.2""
のようなタイプでさえ、実際のビットレート(最大ビットレートのみ)などの情報は含まれていません。このため、あるタイプが与えられた場合、ユーザーエージェントは、そのタイプのメディアを再生できるかどうか(さまざまな信頼度で)を判断できる場合があり、またはそのタイプのメディアを絶対に再生できないことを判断できる場合もあります。
ユーザーエージェントが再生できないことを知っているタイプとは、例えばコンテナタイプを認識しない、または指定されたコーデックをサポートしていないために、リソースを確実にサポートしていないものを指します。
MIMEタイプ "application/octet-stream"(パラメータなし)は、決してユーザーエージェントが再生できないことを知っているタイプではありません。ユーザーエージェントは、そのタイプを、潜在的なメディアリソースをラベル付けする際に、明示的なContent-Typeメタデータが欠けているのと同等に扱う必要があります。
ここで特別扱いされるのは、パラメータのないMIMEタイプ "application/octet-stream"
のみです。これにパラメータが含まれている場合、それは他のMIMEタイプと同様に扱われます。これは、未知のMIMEタイプのパラメータは無視すべきだというルールからの逸脱です。
media.canPlayType(type)
すべての現在のエンジンでサポートされています。
ユーザーエージェントが与えられたタイプのメディアリソースを再生できるかどうかに対する信頼度に基づいて、空の文字列(否定的な応答)、"maybe"、または"probably"を返します。
canPlayType(type) メソッドは、type がユーザーエージェントが再生できないことを知っているタイプである場合、または
"application/octet-stream"
タイプである場合、空の文字列を返さなければなりません。ユーザーエージェントがそのタイプがレンダリング可能であると自信を持っている場合には、"probably" を返さなければなりません。そうでなければ、"maybe" を返さなければなりません。実装者は、タイプがサポートされているかどうかを確実に確認できない限り、"maybe"
を返すことを推奨します。一般的に、ユーザーエージェントは、codecsパラメータが存在しない場合、そのパラメータを許可するタイプに対して "probably"
を返すべきではありません。
このスクリプトは、ユーザーエージェントが(架空の)新しいフォーマットをサポートしているかどうかをテストし、video要素を動的に使用するかどうかを決定します。
< section id = "video" >
< p >< a href = "playing-cats.nfv" > Download video</ a ></ p >
</ section >
< script >
const videoSection = document. getElementById( 'video' );
const videoElement = document. createElement( 'video' );
const support = videoElement. canPlayType( 'video/x-new-fictional-format;codecs="kittens,bunnies"' );
if ( support === "probably" ) {
videoElement. setAttribute( "src" , "playing-cats.nfv" );
videoSection. replaceChildren( videoElement);
}
</ script >
type属性は、source要素で、ユーザーエージェントがレンダリングできないフォーマットを使用するリソースのダウンロードを回避することができます。
media.networkState
すべての現在のエンジンでサポートされています。
要素の現在のネットワーク活動状態を、以下のリストに示すコードの中から返します。
メディア要素がネットワークとやり取りする際に、その現在のネットワーク活動は、networkState属性によって表されます。取得時に、次の値のいずれかを返さなければなりません:
NETWORK_EMPTY(数値 0)
NETWORK_IDLE(数値 1)
NETWORK_LOADING(数値 2)
NETWORK_NO_SOURCE(数値 3)
リソース選択アルゴリズムは、networkState属性の値が変わる正確なタイミングと、この状態の変化を示すイベントがいつ発生するかを記述しています。
media.load()
すべての現在のエンジンでサポートされています。
要素をリセットし、新しいメディアリソースの選択と読み込みを最初から開始させます。
すべてのメディア要素には、自動再生可能フラグがあり、これは最初に true の状態で開始し、ロードイベントを遅延させるフラグがあり、これは最初に false の状態で開始する必要があります。ロードイベントを遅延させるフラグが true の場合、要素はそのドキュメントのロードイベントを遅延させる必要があります。
load()メソッドがメディア要素で呼び出されたとき、ユーザーエージェントはメディア要素の読み込みアルゴリズムを実行する必要があります。
メディア要素には、最初は false に設定されている関連するブール値の現在停止しているかどうかが存在します。
メディア要素の読み込みアルゴリズムは、次のステップで構成されています。
この要素の現在停止しているかどうかを false に設定します。
この要素に対して既に実行中のリソース選択アルゴリズムのインスタンスを中止します。
pending tasksを、メディア要素のメディア要素イベントタスクソースからのすべてのタスクのリストにします。
pending tasks内の、保留中の再生プロミスを解決するまたは保留中の再生プロミスを拒否するタスクに対しては、それらのプロミスをキューに入れられた順番に従って即座に解決または拒否します。
pending tasks内の各タスクをそのタスクキューから削除します。
基本的に、メディア要素が新しいリソースの読み込みを開始すると、保留中のイベントやコールバックが破棄され、解決/拒否が保留中のプロミスが即座に解決/拒否されます。
メディア要素のnetworkStateがNETWORK_LOADINGまたはNETWORK_IDLEに設定されている場合、メディア要素タスクをキューに入れる必要があります。
イベントを発生させるという指定されたメディア要素に基づいて、abortという名前のイベントをメディア要素に発生させます。
メディア要素のnetworkStateがNETWORK_EMPTYに設定されていない場合は、以下を実行します。
メディア要素タスクをキューに入れるという指定されたメディア要素に基づいて、イベントを発生させるという作業を続けます。イベント名は、emptiedであり、対象のメディア要素です。
もしメディア要素のフェッチプロセスが進行中であれば、ユーザーエージェントはそれを停止する必要があります。
メディアプロバイダーオブジェクトがMediaSourceオブジェクトである場合、それをデタッチします。
readyStateがHAVE_NOTHINGに設定されていない場合、それをその状態に設定します。
もしpaused属性が
false の場合、以下を実行します。
paused属性を
true に設定します。
保留中の再生プロミスを取得すると保留中の再生プロミスを拒否する、その結果と"AbortError"を持つDOMExceptionと共に拒否します。
seekingが
true の場合、それを false に設定します。
現在の再生位置を 0 に設定します。
公式の再生位置を 0 に設定します。
これにより公式の再生位置が変更された場合、メディア要素タスクをキューに入れるという指定されたメディア要素に基づいて、イベントを発生させるという作業を続けます。イベント名は、timeupdateです。
タイムラインオフセットを NaN(Not-a-Number)に設定します。
duration属性を
NaN(Not-a-Number)に更新します。
ユーザーエージェントは、この特定の期間の変更に対してdurationchangeイベントを発生させません。
playbackRate属性をdefaultPlaybackRate属性の値に設定します。
メディア要素のリソース選択アルゴリズムを呼び出します。
この要素の以前の再生中のメディアリソースの再生は停止します。
メディア要素のリソース選択アルゴリズムは次のようになります。このアルゴリズムは常にタスクの一部として呼び出されますが、このアルゴリズムの最初のステップの一つは戻り、残りのステップを並行して実行し続けます。さらに、このアルゴリズムはイベントループのメカニズムと密接に連携しています。特に、同期セクションを持っており(これらはイベントループアルゴリズムの一部としてトリガーされます)。このようなセクション内のステップは⌛でマークされています。
要素のnetworkState属性をNETWORK_NO_SOURCEに設定します。
要素のポスター表示フラグを true に設定します。
メディア要素のロードイベントを遅延させるフラグを true に設定します(これによりロードイベントが遅延します)。
安定した状態を待つことを行い、このアルゴリズムを呼び出したタスクが続行できるようにします。同期セクションは、このアルゴリズムの残りのすべてのステップで構成されており、アルゴリズムが同期セクションが終了したと通知するまで続きます。(同期セクション内のステップは⌛でマークされています。)
⌛ もしメディア要素のパーサーによってブロックされているフラグが false の場合、保留中のテキストトラックのリストを作成します。
⌛ もしメディア要素にメディアプロバイダーオブジェクトが割り当てられている場合、modeをobjectに設定します。
⌛ それ以外の場合、もしメディア要素にメディアプロバイダーオブジェクトが割り当てられていないが、src属性がある場合、modeをattributeに設定します。
⌛ それ以外の場合、もしメディア要素にメディアプロバイダーオブジェクトが割り当てられておらず、src属性もなく、source要素の子がある場合、modeをchildrenに設定し、candidateを最初のそのようなsource要素の子として木構造順で設定します。
⌛ それ以外の場合、メディア要素にはメディアプロバイダーオブジェクトが割り当てられておらず、src属性もなく、source要素の子もありません:
⌛networkStateをNETWORK_EMPTYに設定します。
⌛ 要素のロードイベントを遅延させるフラグを false に設定します。これにより、ロードイベントを遅延させることが停止します。
同期セクションを終了し、戻ります。
⌛メディア要素のnetworkState属性をNETWORK_LOADINGに設定します。
⌛メディア要素タスクをキューに入れるという指定されたメディア要素に基づいて、イベントを発生させるという作業を続けます。イベント名は、loadstartです。
以下のリストから適切なステップを実行します。
⌛currentSrc属性を空の文字列に設定します。
リソースフェッチアルゴリズムを割り当てられたメディアプロバイダーオブジェクトと共に実行します。このアルゴリズムがこのアルゴリズムを中止せずに終了した場合、ロードは失敗します。
メディアプロバイダーで失敗: このステップに到達したことは、メディアリソースの読み込みが失敗したことを示します。保留中の再生プロミスを取得するとメディア要素タスクをキューに入れるという指定されたメディア要素に基づいて、専用のメディアソース失敗ステップを実行します。
前のステップでキューに入れられたタスクが実行されるまで待ちます。
戻ります。このアルゴリズムが再度トリガーされるまで、要素は別のリソースの読み込みを試みません。
⌛urlRecordをURL
のエンコーディングと解析の結果に設定します。これは、最後に変更された際のsrc属性の値に基づいて、メディア要素のノードドキュメントに対して相対的に行われます。
⌛urlRecordが失敗でない場合、currentSrc属性をurlRecordにURL シリアライザを適用した結果に設定します。
urlRecordが失敗でない場合、urlRecordを使用してリソースフェッチアルゴリズムを実行します。このアルゴリズムがこのアルゴリズムを中止せずに終了した場合、ロードは失敗します。
attribute で失敗: このステップに到達したことは、メディアリソースの読み込みが失敗したか、urlRecordが失敗であることを示します。保留中の再生プロミスを取得するとメディア要素タスクをキューに入れるという指定されたメディア要素に基づいて、専用のメディアソース失敗ステップを実行します。
前のステップでキューに入れられたタスクが実行されるまで待ちます。
戻ります。このアルゴリズムが再度トリガーされるまで、要素は別のリソースの読み込みを試みません。
⌛pointerは、メディア要素の子リスト内で定義された 2 つの隣接するノードによって定義される位置です。リストの開始(リスト内の最初の子の前、あるいはどんな子であっても)、およびリストの終了(リストの最後の子の後、もし存在する場合)は、それ自体がノードとみなされます。一方のノードは、pointerの前のノードであり、もう一方のノードはpointerの後のノードです。初期状態では、pointerは、candidateノードと次のノード(存在する場合)の間、またはリストの最後のノードである場合はリストの終了の間にあります。
ノードが挿入されたり、削除されたりする場合、pointerは以下のように更新されます:
その他の変更はpointerに影響を与えません。
⌛候補を処理する: もしcandidateがsrc属性を持っていない場合、またはそのsrc属性の値が空の文字列である場合、同期セクションを終了し、以下の要素で失敗ステップに移動します。
⌛もしcandidateがmedia属性を持っており、その値が環境に一致しない場合、同期セクションを終了し、以下の要素で失敗ステップに移動します。
⌛urlRecordをURL
のエンコーディングと解析の結果に設定します。これは、最後に変更された際のcandidateのsrc属性の値に基づいて、candidateのノードドキュメントに対して相対的に行われます。
⌛urlRecordが失敗である場合、同期セクションを終了し、以下の要素で失敗ステップに移動します。
⌛もしcandidateがtype属性を持ち、その値がMIME
タイプ(そのパラメーターを定義するタイプの場合、codecs
パラメーターを含む)として解析されたとき、ユーザーエージェントがレンダリングできないことを知っているタイプを表す場合、同期セクションを終了し、以下の要素で失敗ステップに移動します。
⌛currentSrc属性をurlRecordにURL シリアライザを適用した結果に設定します。
urlRecordを使用してリソースフェッチアルゴリズムを実行します。このアルゴリズムがこのアルゴリズムを中止せずに終了した場合、ロードは失敗します。
要素で失敗:メディア要素タスクをキューに入れるという指定されたメディア要素に基づいて、イベントを発生させるという作業を続けます。イベント名は、errorで、対象はcandidateです。
安定した状態を待つことを行います。同期セクションは、このアルゴリズムの残りのすべてのステップで構成されており、アルゴリズムが同期セクションが終了したと通知するまで続きます。(同期セクション内のステップは⌛でマークされています。)
⌛次の候補を見つける:candidateを null に設定します。
⌛検索ループ: pointerの後のノードがリストの終了である場合、以下の待機ステップにジャンプします。
⌛もしpointerの後のノードがsource要素である場合、その要素をcandidateとします。
⌛pointerを進め、pointerの前のノードが現在のpointerの後のノードになり、pointerの後のノードが以前のpointerの後のノードの後のノードになります(もし存在する場合)。
⌛candidateが null の場合、検索ループステップに戻ります。それ以外の場合は、候補を処理するステップに戻ります。
⌛待機: 要素のnetworkState属性をNETWORK_NO_SOURCEの値に設定します。
⌛ 要素のポスター表示フラグを true に設定します。
⌛メディア要素タスクをキューに入れるという指定されたメディア要素に基づいて、要素のロードイベントを遅延させるフラグを false に設定します。これにより、ロードイベントを遅延させることが停止します。
pointerの後のノードがリストの終了以外のノードになるまで待機します。(このステップは永遠に待機するかもしれません。)
安定した状態を待つことを行います。同期セクションは、このアルゴリズムの残りのすべてのステップで構成されており、アルゴリズムが同期セクションが終了したと通知するまで続きます。(同期セクション内のステップは⌛でマークされています。)
⌛ 要素のロードイベントを遅延させるフラグを再び true に設定します(これにより、ロードイベントがまだ発生していない場合に、再度遅延させます)。
⌛ 要素のnetworkStateをNETWORK_LOADINGに戻します。
⌛ 上記の次の候補を見つけるステップに戻ります。
リストのpromisesと共に実行される専用のメディアソース失敗ステップは、次のステップです:
error属性をMediaErrorを作成する結果に設定し、MEDIA_ERR_SRC_NOT_SUPPORTEDを返します。
要素のnetworkState属性をNETWORK_NO_SOURCEに設定します。
要素のポスター表示フラグを true に設定します。
イベントを発生させるという作業を続けます。イベント名は、errorであり、対象はメディア要素です。
保留中の再生プロミスを拒否するをpromisesと共に、"NotSupportedError"のDOMExceptionを使用して実行します。
要素のロードイベントを遅延させるフラグを false に設定します。これにより、ロードイベントを遅延させることが停止します。
与えられたメディア応答を検証するためには、応答 response、メディアリソース resource、および
"entire resource" または (number, number or "until end") のタプル byteRange
を与える必要があります。
response がネットワークエラーの場合、falseを返します。
byteRange が "entire resource" の場合、trueを返します。
internalResponse を response の安全でない応答として設定します。
internalResponse のステータスが200の場合、trueを返します。
internalResponse のステータスが206でない場合、falseを返します。
internalResponseからcontent-range 値を抽出する結果が失敗した場合、falseを返します。
抽出された値は使用されず、特にbyteRangeと比較されません。このステップは、`Content-Range`ヘッダーの構文検証として機能しますが、応答の`Content-Range`値がリクエストの`Range`値と一致しない場合、それは失敗と見なされません。
internalResponse のURLが
null の場合、origin を "rewritten" に設定します。それ以外の場合は、internalResponse のURLのオリジンに設定します。
previousOrigin をresourceのオリジンとして設定します。
以下のいずれかが真である場合:
previousOrigin が "none" である。
origin とpreviousOriginが "rewritten" である。
origin とpreviousOriginがオリジンであり、originがpreviousOriginと同じオリジンである。
この場合、resource のオリジンをoriginに設定します。
それ以外の場合、responseがCORS-クロスオリジンである場合は、falseを返します。
それ以外の場合、resource のオリジンを"multiple"に設定します。
これは、範囲ヘッダーを持つ不透明な応答が、異なるオリジンからの他の応答と一緒にパッチされることで情報が漏洩しないようにします。
true を返します。
メディア要素 および指定された URL レコード または メディアプロバイダオブジェクト のための リソースフェッチアルゴリズム は次の通りです:
アルゴリズムが メディアプロバイダーオブジェクト または、 URLレコード が ブロブURLエントリ であり、その ブロブURLエントリ の オブジェクト が メディアプロバイダーオブジェクト である場合、 mode を ローカル に設定します。それ以外の場合、 mode を リモート に設定します。
mode が リモート の場合、 current media resource を、このアルゴリズムに渡された URLレコード で指定されたリソースに設定します。そうでない場合、 current media resource を メディアプロバイダーオブジェクト で指定されたリソースに設定します。いずれにしても、 current media resource は要素の メディアリソース になります。
メディアリソース固有のテキストトラック を、 メディア要素 の 保留中のテキストトラックのリスト から削除します(もしあれば)。
次のリストから適切な手順を実行します。
次のサブステップを任意で実行します。これは、ユーザーエージェントがリソースを明示的にユーザーが要求するまで取得しないことを意図している場合の期待される動作です(例: preload
属性の none
キーワードを実装する方法として)。
networkState
を NETWORK_IDLE
に設定します。
メディア要素タスクをキューに追加
し、メディア要素 に対して イベントを発火 して、suspend
という名前のイベントを要素で発火させます。
メディア要素タスクをキューに追加 し、メディア要素 の delaying-the-load-event フラグ を false に設定します。これにより ロードイベントの遅延 を停止します。
タスクが実行されるのを待ちます。
実装定義 のイベント(例: ユーザーがメディア要素の再生を開始することを要求する)を待ちます。
要素の delaying-the-load-event フラグ を再度 true に設定します(これにより ロードイベントを遅延 させます。まだ発火していない場合)。
networkState
を NETWORK_LOADING
に設定します。
メディア要素 が audio
要素である場合は destination
を「audio」、それ以外の場合は「video」に設定します。
request を current media resource の URL
レコード、destination、および現在の状態の メディア要素 の crossorigin
コンテンツ属性を基に 潜在的な CORS リクエストを作成
した結果に設定します。
request の クライアント を メディア要素 の ノードドキュメント の 関連設定オブジェクト に設定します。
request の イニシエータータイプ を destination に設定します。
byteRange を "entire resource" または (数値, 数値 または
"until end") のタプルとして、メディアデータ
内の欠落データを満たすために必要なバイト範囲に設定します。この値は 実装定義
であり、コーデック、ネットワーク条件、その他のヒューリスティックに依存する可能性があります。ユーザーエージェントはリソースを完全にフェッチすることを決定する場合があり、その場合
byteRange は "entire resource"、バイトオフセットから末尾までフェッチする場合は
byteRange は (数値, "until end") になり、2つのバイトオフセット間の範囲をフェッチする場合は
byteRange は2つのオフセットを表す (数値, 数値) のタプルになります。
byteRange が "entire resource" でない場合:
Fetch request を実行し、processResponse を次のステップに設定し、response response を処理します:
global を メディア要素 の ノードドキュメント の 関連グローバルオブジェクト に設定します。
updateMedia を メディア要素タスクをキューに追加 し、メディア要素 に対して、以下の メディアデータ処理ステップリスト の最初の適切なステップを実行します(この処理は、適切なメディア要素イベントタスクソースに相対して行われるため、新しいタスクを使用します。これはネットワーキングタスクソースを使用するのではありません)。
processEndOfMedia を次のステップに設定します: フェッチプロセスがエラーなく完了し、メディアデータのデコードを含め、すべてのデータがユーザーエージェントにネットワークアクセスなしで利用可能になった場合、ユーザーエージェントは以下の 最終ステップ に進む必要があります。これは、例えばウェブラジオのような無限のリソースをストリーミングする場合や、リソースがユーザーエージェントのキャッシュ能力を超える長さである場合などには、決して発生しないかもしれません。
検証 の結果が current media resource と byteRange に対して false である場合、これらのステップを中止します。
それ以外の場合、インクリメンタルに読み取ります response の ボディ を、updateMedia、processEndOfMedia、空のアルゴリズム、およびglobal を使用して読み取ります。
メディアデータ
を、response の安全でないレスポンス
の内容で更新します。response はCORS-same-origin または
CORS-cross-origin
である可能性があり、これにより、API で参照される字幕が公開されるかどうか、また、ビデオ要素の場合は、ビデオがキャンバスに描画されたときにキャンバスが汚染されるかどうかが影響します。
メディア要素の停止タイムアウト は 実装定義 の時間で、約3秒であるべきです。 メディア要素 が積極的にメディアデータを取得しようとしている間に、メディア要素の停止タイムアウトに等しい期間、データを受信できなかった場合、ユーザーエージェントは メディア要素タスクをキューに追加 し、メディア要素に対して次の操作を行います:
ユーザーエージェントは、メディアデータ のダウンロードを選択的にブロックまたは遅延させることをユーザーに許可する場合があります。 メディア要素 のダウンロードが完全にブロックされた場合、ユーザーエージェントは接続が閉じられたかのようにではなく、停止しているかのように動作する必要があります。また、ユーザーエージェントは、同じ帯域幅を共有する他の接続とのバランスを取るために、ダウンロード速度を自動的に調整することがあります。
ユーザーエージェントは、いつでも追加のコンテンツをダウンロードしないことを決定する場合があります。例えば、1時間のメディアリソースの5分間をバッファリングした後、ユーザーがリソースを再生するかどうかを決定するまで、対話型リソースでユーザー入力を待っている間、またはユーザーがページから離れた場合などです。メディア要素
のダウンロードが一時停止された場合、ユーザーエージェントはメディア要素タスクをキューに追加
し、メディア要素のnetworkStateをNETWORK_IDLEに設定し、イベントを発火してsuspendという名前のイベントを要素で発火させる必要があります。リソースのダウンロードが再開された場合、ユーザーエージェントはメディア要素タスクをキューに追加し、メディア要素のnetworkStateをNETWORK_LOADINGに設定します。これらのタスクのキューイングの間、ロードは一時停止されます(したがって、上記のように進行イベントは発生しません)。
preload属性は、著者が考える推奨されるバッファリング量についてのヒントを提供します。たとえautoplay属性がない場合でも。
ユーザーエージェントがダウンロードを完全に一時停止することを決定した場合、例えばユーザーが再生を開始するまで追加のコンテンツをダウンロードしない場合、ユーザーエージェントはメディア要素タスクをキューに追加し、メディア要素のdelaying-the-load-eventフラグをfalseに設定して、ロードイベントの遅延を停止する必要があります。
上記のステップはリクエストを発行するアルゴリズムを提供していますが、ユーザーエージェントは特にエラー条件に直面した場合、これらと正確に同じ手段以外を使用することがあります。例えば、ユーザーエージェントはサーバーに再接続したり、ストリーミングプロトコルに切り替えたりすることができます。ユーザーエージェントはリソースをエラーとしてのみ考慮し、上記のステップのエラーブランチに進む必要がありますが、これはユーザーエージェントがリソースのフェッチをあきらめた場合に限ります。
メディアリソースの形式を判断するために、ユーザーエージェントはオーディオおよびビデオを特定するためのスニッフィングルールを使用する必要があります。
ロードが一時停止されていない間(下記参照)、350ミリ秒ごと(±200ミリ秒)または受信するバイトごとに(頻度の少ない方に従う)、メディア要素タスクをキューに追加し、メディア要素に対して:
ユーザーエージェントがまだメディアリソースの一部を取得するためにネットワークアクセスを必要とする場合、ユーザーエージェントはこのステップに留まる必要があります。
例えば、ユーザーエージェントがビデオの前半部分を破棄した場合、ユーザーエージェントは再生が終了した後もこのステップに留まります。なぜなら、ユーザーが最初に戻ることを期待している可能性が常にあるからです。実際、この状況では、再生が終了した後、ユーザーエージェントは前述のようにsuspendイベントを発火することになります。
current media resource で説明されているリソースがある場合、メディアデータが含まれています。これはCORS-same-originです。
current media resource が生データストリーム(例: File
オブジェクトからのストリーム)である場合、メディアリソースの形式を判断するために、ユーザーエージェントはオーディオおよびビデオを特定するためのスニッフィングルールを使用する必要があります。そうでなければ、データストリームが事前にデコードされている場合、形式は関連する仕様によって与えられる形式です。
current media resource の新しいデータが利用可能になるたびに、メディア要素タスクをキューに追加 し、メディア要素に対して以下のメディアデータ処理ステップリストの最初の適切なステップを実行します。
current media resource が完全に終了した場合(例: すべてのバイトが処理された場合)、デコードエラーがなかった場合、ユーザーエージェントは以下の
最終ステップ に進む必要があります。これは、例えば current media resource が MediaStream
である場合などには、決して発生しないかもしれません。
メディアデータ処理手順リストは以下の通りです:
DNSエラー、HTTP 4xxおよび5xxエラー(他のプロトコルでの同等エラー)、およびユーザーエージェントが現在のメディアリソースが使用可能かどうかを確認する前に発生する他の致命的なネットワークエラー、ならびに未対応のコンテナフォーマットを使用しているか、すべてのデータに対して未対応のコーデックを使用している場合、ユーザーエージェントは次の手順を実行しなければなりません:
ユーザーエージェントは取得プロセスをキャンセルするべきです。
このサブアルゴリズムを中止し、リソース選択アルゴリズムに戻ります。
AudioTrackオブジェクトを作成してオーディオトラックを表します。
メディア要素のaudioTracks属性のAudioTrackListオブジェクトを、新しいAudioTrackオブジェクトで更新します。
enableを不明に設定します。
もしメディアリソースや現在のメディアリソースのURLが特定のオーディオトラックを有効にするように示す場合、またはユーザーエージェントがユーザーの体験を向上させるために特定のオーディオトラックの選択を支援する情報を持っている場合: このオーディオトラックが有効にするものの一つである場合、enableをtrueに設定し、そうでない場合はenableをfalseに設定します。
これはメディアフラグメント構文によって引き起こされる可能性がありますが、例えばユーザーエージェントがステレオオーディオトラックよりも5.1サラウンドサウンドオーディオトラックを選択することによっても引き起こされる可能性があります。
enableがまだ不明である場合、メディア要素にまだ有効なオーディオトラックがない場合、enableをtrueに設定し、そうでない場合はenableをfalseに設定します。
enableがtrueの場合、このオーディオトラックを有効にし、そうでない場合はこのオーディオトラックを有効にしません。
イベントを発生させます。名前はaddtrackで、このAudioTrackListオブジェクトに対して、TrackEventを使用し、track属性を新しいAudioTrackオブジェクトで初期化します。
VideoTrackオブジェクトを作成してビデオトラックを表します。
メディア要素のvideoTracks属性のVideoTrackListオブジェクトを、新しいVideoTrackオブジェクトで更新します。
enableを不明に設定します。
もしメディアリソースや現在のメディアリソースのURLが特定のビデオトラックを有効にするように示す場合、またはユーザーエージェントがユーザーの体験を向上させるために特定のビデオトラックの選択を支援する情報を持っている場合: このビデオトラックが最初のそのようなビデオトラックである場合、enableをtrueに設定し、そうでない場合はenableをfalseに設定します。
これもまたメディアフラグメント構文によって引き起こされる可能性があります。
enableがまだ不明である場合、メディア要素にまだ選択されたビデオトラックがない場合、enableをtrueに設定し、そうでない場合はenableをfalseに設定します。
enableがtrueの場合、このトラックを選択し、以前に選択されていたビデオトラックを選択解除します。そうでない場合、このビデオトラックを選択しません。もし他のトラックが選択解除された場合、changeイベントが発生します。
イベントを発生させます。名前はaddtrackで、このVideoTrackListオブジェクトに対して、TrackEventを使用し、track属性を新しいVideoTrackオブジェクトで初期化します。
これはリソースが使用可能であることを示します。ユーザーエージェントは次のサブステップに従わなければなりません:
メディアタイムラインを確立します。これは、現在の再生位置および最早可能な位置のためのものであり、メディアデータに基づいています。
タイムラインオフセットを、前のステップで確立されたメディアタイムラインに対応するゼロ時点の日付と時間に更新します。メディアリソースから明示的な日付と時間が指定されていない場合、タイムラインオフセットは非数(NaN)に設定されなければなりません。
duration属性を、リソースの最後のフレームの時間(既知の場合)で更新します。これは、上記で確立されたメディアタイムラインに基づいています。もし不明である場合(例えば、理論的には無限であるストリームの場合)、duration属性を正の無限大に更新します。
ユーザーエージェントは、この時点でdurationchangeイベントを発生させるために、メディア要素タスクをキューに追加します。
video要素の場合、videoWidthおよびvideoHeight属性を設定し、メディア要素タスクをキューに追加して、イベントを発生させます。名前はresizeで、メディア要素に対して行います。
寸法がその後変更された場合、さらにresizeイベントが発生します。
readyState属性をHAVE_METADATAに設定します。
loadedmetadataDOMイベントは、新しい値に設定されたreadyState属性の一部として発生します。
jumpedをfalseに設定します。
もしメディア要素のデフォルト再生開始位置がゼロより大きい場合、その時点にシークし、jumpedをtrueに設定します。
メディア要素のデフォルト再生開始位置をゼロに設定します。
初期再生位置をゼロに設定します。
もしメディアリソースやURLが特定の開始時間を示す場合、初期再生位置をその時間に設定し、jumpedがまだfalseである場合、その時間にシークします。
例えば、メディアフラグメント構文に対応するメディアフォーマットでは、フラグメントを使用して開始位置を示すことができます。
有効なオーディオトラックがない場合、オーディオトラックを有効にします。これによりchangeイベントが発生します。
選択されたビデオトラックがない場合、ビデオトラックを選択します。これによりchangeイベントが発生します。
一度readyState属性がHAVE_CURRENT_DATAに達すると、loadeddataイベントが発生した後、要素のロードイベント遅延フラグをfalseに設定します。これによりロードイベントの遅延が停止します。
各メディアリソースのメタデータを取得しながらネットワーク使用量を減らそうとしているユーザーエージェントは、ここでバッファリングも停止します。これは、前述の規則に従って行われ、networkState属性がNETWORK_IDLE値に切り替わり、suspendイベントが発生します。
ユーザーエージェントは、メディアリソースの持続時間を判断し、再生を開始する前にこのステップを実行する必要があります。
イベントを発生させます。名前はprogressで、メディア要素に対して行います。
networkStateをNETWORK_IDLEに設定し、イベントを発生させます。名前はsuspendで、メディア要素に対して行います。
ユーザーエージェントがメディアデータを破棄し、その後再び取得するためにネットワーク活動を再開する必要がある場合、ユーザーエージェントはメディア要素タスクをキューに追加し、メディア要素に対してnetworkStateをNETWORK_LOADINGに設定します。
ユーザーエージェントがメディアリソースを保持できる場合、アルゴリズムは以下の最終ステップに進み、アルゴリズムを中止します。
ユーザーエージェントがメディアリソースの使用可能性を確認した後 (つまり、メディア要素のreadyState属性がもはやHAVE_NOTHINGでない場合)
に致命的なネットワークエラーが発生した場合、ユーザーエージェントは次のステップを実行する必要があります:
ユーザーエージェントは取得プロセスをキャンセルする必要があります。
error属性を、メディアエラーを作成する結果として、MEDIA_ERR_NETWORKを設定します。
要素のnetworkState属性をNETWORK_IDLE値に設定します。
要素のロードイベント遅延フラグをfalseに設定します。これによりロードイベントの遅延が停止します。
イベントを発生させます。名前はerrorで、メディア要素に対して行います。
全体のリソース選択アルゴリズムを中止します。
ユーザーエージェントがメディアリソースの使用可能性を確認した後 (つまり、メディア要素のreadyState属性がもはやHAVE_NOTHINGでない場合)
に、メディアデータのデコードに致命的なエラーが発生した場合、ユーザーエージェントは次のステップを実行する必要があります:
ユーザーエージェントは取得プロセスをキャンセルする必要があります。
error属性を、メディアエラーを作成する結果として、MEDIA_ERR_DECODEを設定します。
要素のnetworkState属性をNETWORK_IDLE値に設定します。
要素のロードイベント遅延フラグをfalseに設定します。これによりロードイベントの遅延が停止します。
イベントを発生させます。名前はerrorで、メディア要素に対して行います。
全体のリソース選択アルゴリズムを中止します。
ユーザーが「停止」ボタンを押すなどして、取得プロセスが中断された場合、ユーザーエージェントは次のステップを実行する必要があります。これらのステップは、これらのステップが実行されている間にload()メソッドが呼び出された場合には実行されません。その特定の中断に対処するためのステップは、上記の通りです。
ユーザーエージェントは取得プロセスをキャンセルする必要があります。
error属性を、メディアエラーを作成する結果として、MEDIA_ERR_ABORTEDを設定します。
イベントを発生させます。名前はabortで、メディア要素に対して行います。
もしメディア要素のreadyState属性がHAVE_NOTHINGと等しい場合、要素のnetworkState属性をNETWORK_EMPTY値に設定し、要素のポスターフラグを表示に設定し、イベントを発生させます。名前はemptiedで、要素に対して行います。
それ以外の場合、要素のnetworkState属性をNETWORK_IDLE値に設定します。
要素のロードイベント遅延フラグをfalseに設定します。これによりロードイベントの遅延が停止します。
全体のリソース選択アルゴリズムを中止します。
サーバーが部分的に使用可能なデータを返し、最適にレンダリングできない場合、ユーザーエージェントは処理可能な部分だけをレンダリングし、残りを無視する必要があります。
メディアデータがCORS-same-originである場合、関連データを使用してメディアリソース固有のテキストトラックを公開するための手順を実行します。
クロスオリジンのビデオは字幕を公開しません。これは、悪意のあるサイトがユーザーのイントラネット上の機密ビデオから字幕を読み取る攻撃を防ぐためです。
最終ステップ:ユーザーエージェントがこのステップに到達した場合 (これはリソース全体が読み込まれ、保持されている場合にのみ発生します)、全体のリソース選択アルゴリズムを中止します。
メディア要素がメディア要素のメディアリソース固有トラックを忘れる際に、ユーザーエージェントは、メディア要素のテキストトラックのリストからすべてのメディアリソース固有のテキストトラックを削除し、次にメディア要素のaudioTracks属性のAudioTrackListオブジェクトを空にし、次にメディア要素のvideoTracks属性のVideoTrackListオブジェクトを空にします。これに関連して、イベント(特にremovetrackイベント)は発生しません。代わりに、このアルゴリズムを呼び出すアルゴリズムによって発生するerrorおよびemptiedイベントを使用できます。
preload属性は、以下のキーワードと状態を持つ列挙型属性です。
| キーワード | 状態 | 簡単な説明 |
|---|---|---|
auto
| 自動 | ユーザーエージェントに、サーバーへのリスクなしにユーザーのニーズを最優先にするように、楽観的にリソース全体をダウンロードすることも含めて、指示するヒントを与えます。 |
| (空文字列) | ||
none
| なし | ユーザーエージェントに対し、著者がメディアリソースをユーザーが必要とするとは考えていないか、サーバーが不要なトラフィックを最小限に抑えたいと考えていることを示唆するヒントを与えます。この状態は、バッファリングが始まった場合(例: ユーザーが「再生」ボタンを押したとき)に、実際にメディアリソースをどれだけ積極的にダウンロードするかについてはヒントを提供しません。 |
metadata
| メタデータ | ユーザーエージェントに、著者がメディアリソースをユーザーが必要とするとは考えていないが、リソースのメタデータ(寸法、トラックリスト、期間など)を取得すること、場合によっては最初の数フレームを取得することが合理的であると考えていることを示唆するヒントを与えます。ユーザーエージェントがメタデータ以上を正確に取得しない場合、メディア要素は、readyState属性がHAVE_METADATAに設定されますが、通常はいくつかのフレームも取得されるため、おそらくHAVE_CURRENT_DATAまたはHAVE_FUTURE_DATAになります。メディアリソースが再生されているときに、帯域幅を制限する必要があることをユーザーエージェントに示唆します。例えば、ダウンロード速度を可能な限り遅くし、安定した再生を維持するためにメディアデータを取得することを提案します。
|
属性の欠損値デフォルトと無効値デフォルトはどちらも実装依存ですが、メタデータ状態が、サーバー負荷を減らしながら最適なユーザー体験を提供する妥協案として推奨されています。
属性は、メディアリソースがバッファリングまたは再生されている間であっても変更可能です。上記の表の説明は、そのことを念頭に置いて解釈する必要があります。
著者は属性を「none」または「metadata」から「auto」にユーザーが再生を開始した後に動的に切り替えることがあります。例えば、多くのビデオがあるページでは、リクエストされるまでこれらのビデオがダウンロードされないように指定するが、一度リクエストされた場合は積極的にダウンロードすることを示すために使用されるかもしれません。
preload属性は、著者が最良のユーザー体験をもたらすと考えるものについて、ユーザーエージェントにヒントを提供することを目的としています。この属性は、例えば明示的なユーザー設定や利用可能な接続性に基づいて、完全に無視されることもあります。
preloadIDL属性は、同名の内容属性を反映し、既知の値のみに制限される必要があります。
autoplay属性は、preload属性をオーバーライドすることができます(メディアが再生される場合、それがpreload属性によって示唆されるヒントに関係なく、自然にバッファリングが必要であるため)。ただし、両方を含めることはエラーではありません。
media.buffered
現在のすべてのエンジンでサポートされています。
TimeRangesオブジェクトを返します。このオブジェクトは、ユーザーエージェントがバッファリングしたメディアリソースの範囲を表します。
buffered属性は、新しい静的な正規化されたTimeRangesオブジェクトを返しなければなりません。このオブジェクトは、ユーザーエージェントがバッファリングしたメディアリソースの範囲を表します。この属性が評価される時点で、ユーザーエージェントは、たとえそれが煩雑な検査によってしか判断できないものであっても、利用可能な範囲を正確に決定しなければなりません。
通常、これはゼロ点を基準とした単一の範囲になりますが、例えば、ユーザーエージェントがシークに応じてHTTPレンジリクエストを使用する場合、複数の範囲が存在する可能性があります。
ユーザーエージェントは、以前にバッファリングされたデータを破棄することがあります。
したがって、ある時点でbuffered属性によって返されるオブジェクトの範囲に含まれていた時間位置が、後の時点で同じ属性によって返されるオブジェクトの範囲に含まれなくなることがあります。
新しいオブジェクトを毎回返すことは、属性ゲッターにとって悪いパターンであり、変更にコストがかかるためここでのみ定められています。新しいAPIにはコピーされるべきではありません。
media.duration
現在のすべてのエンジンでサポートされています。
メディアリソースの長さを秒単位で返します。このとき、メディアリソースの開始が時間ゼロに設定されていると仮定します。
期間が利用できない場合はNaNを返します。
無限ストリームの場合はInfinityを返します。
media.currentTime [ = value ]
現在のすべてのエンジンでサポートされています。
公式再生位置を秒単位で返します。
指定した時間にシークするように設定できます。
メディアリソースには、メディアタイムラインがあり、時間(秒単位)をメディアリソース内の位置にマッピングします。タイムラインの起点は、その最も早く定義された位置です。タイムラインの期間は、その最後に定義された位置です。
メディアタイムラインの確立: もしメディアリソースが、起点が負でない明示的なタイムライン(すなわち、各フレームに特定の時間オフセットを与え、最初のフレームにゼロまたは正のオフセットを与える)を何らかの形で指定する場合、メディアタイムラインはそのタイムラインであるべきです。(メディアリソースがタイムラインを指定できるかどうかは、メディアリソースの形式によります。)メディアリソースが明示的な開始時刻と日付を指定する場合、その時刻と日付はメディアタイムラインのゼロポイントと見なされるべきです。タイムラインオフセットは、時間と日付であり、getStartDate()メソッドを使用して公開されます。
もしメディアリソースが不連続のタイムラインを持っている場合、ユーザーエージェントは、リソースの開始時に使用されたタイムラインをリソース全体にわたって延長し、メディアタイムラインが最も早い可能な位置(以下に定義)の時点から直線的に増加するようにしなければなりません。これにより、基になるメディアデータに順序が狂ったタイムコードや重複するタイムコードが含まれていても、メディアリソースのタイムラインが一貫して線形に進むことが保証されます。
たとえば、2つのクリップを1つのビデオファイルに連結した場合、ビデオ形式は元のクリップの時間を公開しますが、ビデオデータは、たとえば、00:15..00:29、その後に00:05..00:38というタイムラインを公開するかもしれません。しかし、ユーザーエージェントはこれらの時間を公開せず、代わりに00:15..00:29、その後に00:29..01:02というタイムラインを単一のビデオとして公開します。
明示的なタイムラインを持たないメディアリソースの稀なケースでは、メディアタイムライン上のゼロ時間は、メディアリソースの最初のフレームに対応する必要があります。さらに稀なケースとして、フレームの期間も含めた明示的なタイミング情報が一切ないメディアリソースの場合、ユーザーエージェントは各フレームの時間を実装定義の方法で決定しなければなりません。
明示的なタイムラインを持たないが、フレーム期間が明示されているファイル形式の例としては、アニメーションGIF形式があります。タイミングが一切明示されていないファイル形式の例としては、MJPEGストリームの形式としてよく使用されるJPEGプッシュ形式(multipart/x-mixed-replaceでJPEGフレームを含むもの)があります。
タイミング情報のないリソースの場合でも、ユーザーエージェントがサーバーから最初に提供されたフレームよりも早い時点にシークできる場合は、ゼロ時間はメディアリソースの最も早いシーク可能な時点に対応する必要があります。そうでない場合は、ユーザーエージェントがストリームを受信し始めたメディアリソースの最初のフレームに対応する必要があります。
執筆時点では、明示的なフレーム時間オフセットを持たないが、サーバーから送信された最初のフレームの前にシークできる形式は知られていません。
TV放送局からのストリームを考えてみましょう。これは10月の晴れた金曜日の午後にストリーミングを開始し、常に接続してくるユーザーエージェントに対して同じメディアタイムラインでメディアデータを送信し、そのゼロ時間をこのストリームの開始時に設定します。数ヶ月後、このストリームに接続するユーザーエージェントは、受信する最初のフレームの時間が何百万秒もあることに気づくでしょう。getStartDate()メソッドは、常に放送開始日を返し、これにより、コントローラーはスクラバーに相対時間(「8ヶ月4時間12分23秒」)ではなく実際の時間(例:「午後2時30分」)を表示できるようになります。
いくつかの連結されたフラグメントを含むビデオを配信するストリームを考えてみましょう。これは、ユーザーエージェントが特定の時間を要求できないサーバーによって配信され、代わりにビデオデータを決められた順序でストリーミングし、配信される最初のフレームが常にゼロ時間として識別されます。ユーザーエージェントがこのストリームに接続し、2010-03-20
23:15:00 UTCから2010-03-21 00:05:00 UTCまで、および2010-02-12 14:25:00 UTCから2010-02-12 14:35:00
UTCまでのタイムスタンプをカバーするフラグメントを受信した場合、これは0秒から3600秒(一時間)に延びるメディアタイムラインとして公開されます。ストリーミングサーバーが2番目のクリップの終わりで切断されたと仮定すると、duration属性は3600を返すことになります。この場合、getStartDate()メソッドは2010-03-20
23:15:00 UTCに対応するDateオブジェクトを返します。しかし、5分後に別のユーザーエージェントが接続した場合、そのユーザーエージェントはおそらく、2010-03-20
23:20:00 UTCから2010-03-21 00:05:00 UTCまで、2010-02-12 14:25:00 UTCから2010-02-12 14:35:00
UTCまでのタイムスタンプをカバーするフラグメントを受信し、0秒から3300秒(55分)に延びるメディアタイムラインとしてこれを公開することになります。この場合、getStartDate()メソッドは、2010-03-20
23:20:00 UTCに対応するDateオブジェクトを返します。
これらの両方の例において、seekable属性は、コントローラーが実際にUIで表示したい範囲を示します。通常、サーバーが任意の時間へのシークをサポートしていない場合、これはユーザーエージェントがストリームに接続した時点から最新のフレームまでの時間範囲を意味します。ただし、ユーザーエージェントが以前の情報を破棄し始めた場合、実際の範囲は短くなるかもしれません。
いずれの場合でも、ユーザーエージェントは、確立されたメディアタイムラインを使用して最も早い可能な位置(以下に定義)がゼロ以上であることを確認しなければなりません。
メディアタイムラインには、関連する時計もあります。どの時計が使用されるかはユーザーエージェントによって定義され、メディアリソースに依存することがありますが、ユーザーの壁時計に近いものにする必要があります。
メディア要素には現在の再生位置があり、これは最初(すなわちメディアデータがない場合)にはゼロ秒でなければなりません。現在の再生位置はメディアタイムライン上の時間です。
メディア要素には、正式な再生位置もあり、これも最初はゼロ秒に設定されていなければなりません。正式な再生位置は、スクリプトが実行されている間、安定して保たれる現在の再生位置の概算です。
メディア要素には、デフォルトの再生開始位置もあり、これも最初はゼロ秒に設定されていなければなりません。この時間は、メディアが読み込まれる前でも要素をシークできるようにするために使用されます。
各メディア要素にはポスターフラグを表示があり、メディア要素が作成されるとき、このフラグはtrueに設定されていなければなりません。このフラグは、ビデオ要素に対して、ビデオコンテンツの代わりにポスターフレームを表示するタイミングを制御するために使用されます。
currentTime属性は、取得時に、メディア要素のデフォルトの再生開始位置を返さなければなりません。ただし、それがゼロである場合は、要素の正式な再生位置を返さなければなりません。返される値は秒単位で表現されなければなりません。設定時には、メディア要素のreadyStateがHAVE_NOTHINGである場合、新しい値をメディア要素のデフォルトの再生開始位置に設定しなければなりません。それ以外の場合、新しい値を正式な再生位置に設定し、その後新しい値にシークしなければなりません。この新しい値は秒単位で解釈されなければなりません。
リソースがメディアリソースのストリーミングリソースである場合、ユーザーエージェントはそのリソースの特定の部分をバッファから消去された後に取得できなくなるかもしれません。同様に、いくつかのメディアリソースにはゼロから始まらないメディアタイムラインが存在するかもしれません。最も早い可能な位置は、ユーザーエージェントが再び取得できるストリームまたはリソース内の最も早い位置です。これはまた、メディアタイムライン上の時間でもあります。
最も早い可能な位置はAPIに明示的に公開されていません。それは、属性のseekableで返されるオブジェクトの最初の範囲の開始時点、またはそれがない場合は現在の再生位置に対応します。
最も早い可能な位置が変わると、次のようにします。現在の再生位置が最も早い可能な位置よりも前にある場合、ユーザーエージェントはシークしなければなりません。それ以外の場合、過去15~250ミリ秒の間に要素でtimeupdateイベントを発火していない場合、またそのようなイベントのイベントハンドラーがまだ実行中でない場合、ユーザーエージェントはメディア要素タスクをキューに追加し、そのメディア要素でtimeupdateイベントを発火しなければなりません。
上記の要件およびクリップのメタデータが判明したときに発生するリソースフェッチアルゴリズムの要件のために、現在の再生位置は最も早い可能な位置よりも小さくなることはありません。
任意の時点で、ユーザーエージェントがオーディオまたはビデオトラックが終了し、そのトラックに関連するすべてのメディアデータがメディアタイムラインの最も早い可能な位置よりも前に対応していると判断した場合、 ユーザーエージェントはメディア要素タスクをキューに追加することができます。 このメディア要素に対して以下の手順を実行します。
トラックをaudioTracks属性のAudioTrackListオブジェクトから、またはvideoTracks属性のVideoTrackListオブジェクトから削除します。
イベントを発火し、トラックを表すAudioTrackまたはVideoTrackオブジェクトを使用して、removetrackという名前のイベントをメディア要素のAudioTrackListまたはVideoTrackListオブジェクトで発火します。
duration属性は、メディアリソースの終了時点の時間を秒単位で返さなければなりません。もしメディアデータが利用できない場合、この属性はNot-a-Number
(NaN) 値を返さなければなりません。メディアリソースが境界のないもの(例: ストリーミングラジオや終了時刻が発表されていないライブイベントなど)であると知られている場合、この属性は正の無限大 (Infinity)
値を返さなければなりません。
ユーザーエージェントは、メディアリソースの時間を、メディアデータのいずれかを再生する前に、また、readyStateをHAVE_METADATA以上の値に設定する前に、複数のリソースの部分を取得する必要がある場合でも、決定しなければなりません。
メディアリソースの長さが既知の値に変わったとき(例: 不明から既知に変わった場合、または以前に確立された長さから新しい長さに変更された場合)、ユーザーエージェントはメディア要素にメディア要素タスクをキューに追加して、イベントを発火し、durationchangeという名前のイベントをメディア要素に対して発火しなければなりません。(新しいメディアリソースの読み込みの一環として持続時間がリセットされた場合、このイベントは発火されません。)持続時間が変更され、現在の再生位置がメディアリソースの終了時点よりも大きくなる場合、ユーザーエージェントはまた、メディアリソースの終了時点にシークしなければなりません。
何らかの理由で「無限」のストリームが終了した場合、持続時間は正の無限大からストリーム内の最後のフレームまたはサンプルの時間に変わり、durationchangeイベントが発火します。同様に、ユーザーエージェントが最初にメディアリソースの持続時間を正確に決定せずに推定し、その後、新しい情報に基づいて推定を修正した場合、持続時間は変更され、durationchangeイベントが発火します。
いくつかのビデオファイルには、メディアタイムラインのゼロ時間に対応する明示的な日付と時刻があり、タイムラインオフセットとして知られています。初期状態では、タイムラインオフセットはNot-a-Number (NaN)に設定される必要があります。
getStartDate()メソッドは、現在のタイムラインオフセットを表す新しいDateオブジェクトを返さなければなりません。
loop属性は、指定されている場合、メディア要素がメディアリソースの終了時点に到達した際にリソースの開始位置に戻って再生を続けるようにするブール属性です。
すべての現行エンジンでサポートされています。
loopIDL属性は、同名のコンテンツ属性を反映しなければなりません。
media.readyState
すべての現行エンジンでサポートされています。
下記のリストにあるコードから、現在の再生位置に関して、要素の現在の状態を示す値を返します。
メディア要素には、レディ状態があり、これは現在の再生位置でレンダリングする準備がどの程度整っているかを示します。可能な値は次の通りです。特定の時点でのメディア要素のレディ状態は、要素の状態を表す最大の値です。
HAVE_NOTHING(数値値 0)
メディアリソースに関する情報は何も利用できません。現在の再生位置に関するデータはありません。メディア要素のnetworkState属性がNETWORK_EMPTYに設定されている場合、常にHAVE_NOTHING状態になります。
HAVE_METADATA(数値値 1)
リソースの持続時間が利用可能であることを示すのに十分なリソースが取得されました。ビデオ要素の場合、ビデオの寸法も利用可能です。メディアデータは現在の再生位置に関しては利用できません。
HAVE_CURRENT_DATA(数値値 2)
現在の再生位置に関するデータは利用可能ですが、ユーザーエージェントが再生方向にHAVE_METADATA状態に戻らずに現在の再生位置を進められるほどのデータが不足しているか、再生方向にさらに取得できるデータがないかのいずれかです。例えば、ビデオの場合、現在のフレームのデータはあるが、次のフレームのデータがない場合や、再生が終了した場合がこれに該当します。
HAVE_FUTURE_DATA(数値値 3)
現在の再生位置に関するデータが利用可能であり、HAVE_METADATA状態に戻らずに、再生方向に現在の再生位置を少し進めるのに十分なデータも利用可能です。また、テキストトラックが準備完了していることも条件に含まれます。
HAVE_ENOUGH_DATA(数値値 4)
状態HAVE_FUTURE_DATAに記載されたすべての条件が満たされており、さらに次のいずれかの条件が当てはまります:
playbackRateで現在の再生位置が進行しても、再生が終了するまでに利用可能なデータを超えないと推定する場合。
実際には、HAVE_METADATAとHAVE_CURRENT_DATAの違いはほとんどありません。主に、ビデオ要素をキャンバスに描画する場合に、何かが描かれる状態(HAVE_CURRENT_DATA以上)と、何も描かれない状態(HAVE_METADATA以下)を区別する場合に意味があります。
メディア要素のnetworkStateがNETWORK_EMPTYでない場合に、そのレディ状態が変わると、ユーザーエージェントは次のステップに従う必要があります。
次のリストから最初に該当するサブステップのセットを適用します:
HAVE_NOTHINGであり、新しいレディ状態がHAVE_METADATAの場合
メディア要素タスクをキューに追加するを実行し、メディア要素に対して、要素にloadedmetadataという名前のイベントを発火します。
このタスクが実行される前に、イベントループのメカニズムの一環として、適切であればビデオ要素のリサイズがレンダリングに反映されます。
HAVE_METADATAであり、新しいレディ状態がHAVE_CURRENT_DATA以上である場合
これはメディア要素に対してload()アルゴリズムが最後に実行されて以来、初めてのことである場合、ユーザーエージェントはメディア要素タスクをキューに追加するを実行し、要素にloadeddataという名前のイベントを発火します。
新しいレディ状態がHAVE_FUTURE_DATAまたはHAVE_ENOUGH_DATAである場合、次に関連するステップが実行されます。
HAVE_FUTURE_DATA以上であり、新しいレディ状態がHAVE_CURRENT_DATA以下である場合
要素がそのreadyState属性がHAVE_FUTURE_DATA未満に変更される前に潜在的に再生していた場合、そして要素が再生が終了していない場合、またエラーにより停止したり、ユーザーの操作によって一時停止したり、インバンドコンテンツのために一時停止したりしていない場合、ユーザーエージェントはメディア要素タスクをキューに追加するを実行し、要素にtimeupdateという名前のイベントを発火し、メディア要素タスクをキューに追加するを実行し、要素にwaitingという名前のイベントを発火します。
HAVE_CURRENT_DATA以下であり、新しいレディ状態がHAVE_FUTURE_DATAである場合
ユーザーエージェントはメディア要素タスクをキューに追加するを実行し、要素にcanplayという名前のイベントを発火します。
要素のpaused属性がfalseである場合、ユーザーエージェントは要素の再生について通知する必要があります。
HAVE_ENOUGH_DATAである場合
以前のレディ状態がHAVE_CURRENT_DATA以下であった場合、ユーザーエージェントはメディア要素タスクをキューに追加するを実行し、要素にcanplayという名前のイベントを発火し、要素のpaused属性がfalseである場合、要素の再生について通知する必要があります。
ユーザーエージェントはメディア要素タスクをキューに追加するを実行し、要素にcanplaythroughという名前のイベントを発火します。
要素が自動再生の対象でない場合、ユーザーエージェントはこれらのサブステップを中止する必要があります。
ユーザーエージェントは以下のサブステップを実行できます:
paused属性をfalseに設定します。
playという名前のイベントを発火します。
または、要素がビデオ要素である場合、ユーザーエージェントは、要素がビューポートと交差するかどうかを監視し始めることができます。要素がビューポートと交差し始めたとき、要素がまだ自動再生の対象である場合、上記のサブステップを実行します。オプションとして、要素がビューポートと交差しなくなったとき、自動再生可能フラグがまだtrueであり、自動再生属性がまだ指定されている場合、次のサブステップを実行します:
pauseという名前のイベントを発火します。
再生と一時停止のサブステップは、自動再生可能フラグがtrueである限り、要素がビューポートと交差し始めたりやめたりするたびに、何度でも実行される可能性があります。
ユーザーエージェントは自動再生をサポートする必要はなく、ユーザーの好みを尊重することが推奨されています。作成者はスクリプトを使用してビデオの再生を強制するのではなく、自動再生属性を使用することを推奨されており、ユーザーが望まない場合に動作を上書きできるようにすることが推奨されています。
メディア要素のレディ状態がこれらの状態の間で不連続に移動する可能性があります。たとえば、メディア要素の状態が、HAVE_METADATAからHAVE_ENOUGH_DATAへと一気にジャンプし、HAVE_CURRENT_DATAおよびHAVE_FUTURE_DATAの状態を通過しない場合があります。
readyStateIDL属性は、取得時に、メディア要素の現在のレディ状態を表す上記の値を返す必要があります。
autoplay属性は、ブール属性です。存在する場合、ユーザーエージェントは(ここで説明するアルゴリズムに従って)、中断することなくできるだけ早くメディアリソースの再生を自動的に開始します。
作成者はスクリプトを使用して自動再生をトリガーするのではなく、自動再生属性を使用することが推奨されます。これにより、ユーザーが自動再生を望まない場合、たとえばスクリーンリーダーを使用しているときに、動作を上書きすることができます。また、作成者は自動再生の動作をまったく使用せず、ユーザーエージェントがユーザーに再生を明示的に開始させるのを待つことを検討することも推奨されます。
すべての現行エンジンでサポートされています。
autoplayIDL属性は、同じ名前のコンテンツ属性を反映する必要があります。
media.paused
すべての現行エンジンでサポートされています。
再生が一時停止されている場合はtrueを返し、そうでない場合はfalseを返します。
media.ended
すべての現行エンジンでサポートされています。
メディアリソースの再生が終了した場合はtrueを返します。
media.defaultPlaybackRate [ = value ]
HTMLMediaElement/defaultPlaybackRate
すべての現行エンジンでサポートされています。
ユーザーがメディアリソースを早送りや逆再生していないときのデフォルトの再生速度を返します。
デフォルトの再生速度を変更するために設定することができます。
デフォルトの速度は再生には直接影響しませんが、ユーザーが早送りモードに切り替えた場合、通常の再生モードに戻るときには再生速度がデフォルトの再生速度に戻ることが期待されます。
media.playbackRate [ = value ]
すべての現行エンジンでサポートされています。
現在の再生速度を返し、1.0は通常の速度を示します。
再生速度を変更するために設定することができます。
media.preservesPitch
HTMLMediaElement/preservesPitch
playbackRateが1.0でない場合にピッチ補正アルゴリズムが使用されている場合はtrueを返します。デフォルト値はtrueです。
音声のピッチを変更するためにfalseに設定することができます。これにより、メディアリソースの音声のピッチが、playbackRateに応じて上下に変化します。これは、美的およびパフォーマンス上の理由で有用です。
media.played
TimeRangesオブジェクトを返し、ユーザーエージェントが再生したメディアリソースの範囲を表します。
media.play()
すべての現行エンジンでサポートされています。
paused属性をfalseに設定し、メディアリソースを読み込み、必要に応じて再生を開始します。再生が終了していた場合、最初から再開します。
media.pause()
すべての現行エンジンでサポートされています。
paused 属性は、メディア要素 が一時停止しているかどうかを表します。この属性は、初期状態でtrueでなければなりません。
メディア要素 は、readyState 属性が
HAVE_NOTHING
状態、HAVE_METADATA
状態、または HAVE_CURRENT_DATA
状態にある場合、または要素が ユーザー操作のために一時停止 している場合、ブロックされたメディア要素 です。
メディア要素 が 潜在的に再生中 であると言われるのは、その paused 属性がfalseであり、要素が
再生を終了していない、再生が エラーで停止していない など、ブロックされたメディア要素 ではない場合です。
waiting
DOMイベントが、潜在的に再生中の要素が readyState 属性が
HAVE_FUTURE_DATA
より低い値に変更されるために再生を停止する結果として発生する可能性があります。
メディア要素 が 自動再生が可能 であると言われるのは、次のすべてが真である場合です。
paused
属性がtrueであること。autoplay
属性が指定されていること。autoplay"
機能を持っていること。メディア要素は、ユーザーエージェントとシステムが現在のコンテキストでメディア再生を許可している場合、再生が許可されているとされます。
例えば、ユーザーエージェントは、メディア要素のWindowオブジェクトが一時的なアクティベーションを持つ場合にのみ再生を許可することがありますが、ミュートされている間に再生を許可する例外を設けることもあります。
メディア要素は、次の条件を満たしたときに再生が終了したとされます:
要素のreadyState属性がHAVE_METADATA以上であり、
次のいずれかの場合:
または:
ended属性は、最後にイベントループがステップ1に到達したときに、メディア要素が再生を終了しており、再生の方向が前方であった場合にtrueを返し、それ以外の場合はfalseを返さなければなりません。
メディア要素は、次の条件を満たしたときにエラーによって停止したとされます: 要素のreadyState属性がHAVE_METADATA以上であり、ユーザーエージェントが処理中に非致命的なエラーに遭遇し、そのエラーのために現在の再生位置でコンテンツを再生できなくなった場合。
メディア要素は、次の条件を満たしたときにユーザー操作のために一時停止したとされます: paused属性がfalseであり、readyState属性がHAVE_FUTURE_DATAまたはHAVE_ENOUGH_DATAのいずれかであり、ユーザーエージェントがメディアリソース内でリソースを継続するためにユーザーが選択を行う必要がある地点に到達したとき。
メディア要素が再生を終了し、ユーザー操作のために一時停止している場合、同時にそれが可能です。
メディア要素が潜在的に再生中で、ユーザー操作のために一時停止したために再生を停止した場合、ユーザーエージェントはメディア要素タスクをキューに入れ、そのメディア要素でイベントを発火させ、timeupdateという名前のイベントを要素に発生させる必要があります。
メディア要素がインバンドコンテンツのために一時停止したとされるのは、paused属性がfalseであり、readyState属性がHAVE_FUTURE_DATAまたはHAVE_ENOUGH_DATAのいずれかであり、ユーザーエージェントがメディアリソースを再生するのを一時停止して、そのメディアリソースに一時的にアンカーされているがゼロ以外の長さを持つコンテンツを再生する場合、またはメディアリソースのセグメントに一時的にアンカーされているがそのセグメントよりも長い長さを持つコンテンツを再生する場合です。
メディア要素がインバンドコンテンツのために一時停止される例の一つは、ユーザーエージェントが外部のWebVTTファイルから音声説明を再生しているときで、キューのために生成された合成音声がテキストトラックキューの開始時間とテキストトラックキューの終了時間の間の時間よりも長い場合です。
現在の再生位置がメディアリソースの終端に達し、再生の方向が前方の場合、ユーザーエージェントは次の手順に従う必要があります:
メディア要素タスクをキューに入れる際に、メディア要素に対して次の手順を行います:
イベントを発火し、timeupdateという名前のイベントをメディア要素に発生させます。
メディア要素が再生を終了し、再生の方向が前方であり、pausedがfalseである場合、次の手順を実行します:
paused属性をtrueに設定します。
保留中の再生プロミスを取得し、保留中の再生プロミスを拒否し、結果と"AbortError"DOMExceptionを返します。
現在の再生位置が最も早い位置に達し、メディアリソースの再生の方向が後方の場合、ユーザーエージェントはメディア要素タスクをキューに入れ、次にイベントを発火し、timeupdateという名前のイベントを要素に発生させる必要があります。
ここでの「到達」という言葉は、現在の再生位置が通常の再生中に変化する必要があることを意味するものではありません。例えばシークによって到達することもあります。
defaultPlaybackRate属性は、メディアリソースが再生される望ましい速度を、その固有の速度の倍数として示します。この属性は変更可能で、取得時には最後に設定された値を返すか、まだ設定されていない場合は1.0を返す必要があります。設定時には、新しい値に設定されなければなりません。
defaultPlaybackRateは、ユーザーエージェントがユーザーインターフェースをユーザーに公開する際に使用されます。
playbackRate属性は、実際の再生速度を、その固有の速度の倍数として示します。これがdefaultPlaybackRateと等しくない場合、ユーザーが早送りやスローモーション再生などの機能を使用していることを意味します。この属性は変更可能で、取得時には最後に設定された値を返すか、まだ設定されていない場合は1.0を返す必要があります。設定時には、ユーザーエージェントは次の手順に従う必要があります:
指定された値がユーザーエージェントでサポートされていない場合、"NotSupportedError" DOMExceptionをスローします。
playbackRateを新しい値に設定し、要素が潜在的に再生中であれば、再生速度を変更します。
defaultPlaybackRateまたはplaybackRateの属性値が変更されたとき(スクリプトによって設定された場合や、ユーザー操作に応じてユーザーエージェントが直接変更した場合など)、ユーザーエージェントはメディア要素タスクをキューに入れ、メディア要素に対してイベントを発火させ、ratechangeという名前のイベントを発生させる必要があります。ユーザーエージェントは属性の変更をスムーズに処理し、再生において知覚可能なギャップやミュートを発生させてはなりません。
preservesPitchのgetterステップは、再生中にピッチを維持するアルゴリズムが有効である場合にtrueを返すことです。setterステップは、再生に知覚可能なギャップやミュートを発生させることなく、ピッチを維持するアルゴリズムをオンまたはオフに切り替えることです。デフォルトでは、そのようなピッチ維持アルゴリズムは有効でなければなりません(つまり、getterは初期状態でtrueを返します)。
played属性は、属性が評価される時点で、通常の再生中に現在の再生位置の単調な増加によって到達したメディアリソースのメディアタイムライン上の範囲を表す新しい静的な正規化されたTimeRangesオブジェクトを返さなければなりません。
毎回新しいオブジェクトを返すことは、属性ゲッターにとって悪いパターンであり、変更するにはコストがかかるため、ここに保存されています。新しいAPIにコピーしてはいけません。
各メディア要素には、保留中の再生プロミスのリストがあり、初期状態では空でなければなりません。
メディア要素の保留中の再生プロミスを取得するために、ユーザーエージェントは次の手順を実行する必要があります:
promisesを空のプロミスリストとします。
メディア要素の保留中の再生プロミスのリストをpromisesにコピーします。
メディア要素の保留中の再生プロミスのリストをクリアします。
promisesを返します。
メディア要素に対してプロミスのリストpromisesを持つ保留中の再生プロミスを解決するために、ユーザーエージェントはpromises内の各プロミスを未定義で解決する必要があります。
メディア要素に対してプロミスのリストpromisesと例外名errorを持つ保留中の再生プロミスを拒否するために、ユーザーエージェントはpromises内の各プロミスをerrorで拒否する必要があります。
メディア要素の再生について通知するために、ユーザーエージェントは次の手順を実行する必要があります:
保留中の再生プロミスを取得し、その結果をpromisesとします。
次の手順で要素に対してメディア要素タスクをキューに入れる:
保留中の再生プロミスを解決し、promisesを結果として返します。
メディア要素のplay()メソッドが呼び出されたとき、ユーザーエージェントは次の手順を実行する必要があります。
メディア要素が再生が許可されていない場合、プロミスをNotAllowedErrorの"NotAllowedError"のDOMExceptionで拒否された状態で返します。
メディア要素のerror属性がnullでなく、そのコードがMEDIA_ERR_SRC_NOT_SUPPORTEDである場合、プロミスをNotSupportedErrorの"NotSupportedError"のDOMExceptionで拒否された状態で返します。
これは、専用のメディアソースエラー処理手順が実行されたことを意味します。メディア要素ロードアルゴリズムがerror属性をクリアするまで、再生はできません。
promiseを新しいプロミスとし、保留中の再生プロミスのリストにpromiseを追加します。
promiseを返します。
メディア要素に対する内部再生手順は次のとおりです:
メディア要素のnetworkState属性の値がNETWORK_EMPTYの場合、メディア要素のリソース選択アルゴリズムを呼び出します。
再生が終了し、再生の方向が前方の場合、最も早い位置にメディアリソースをシークします。
これは、ユーザーエージェントがメディア要素タスクをキューに入れ、メディア要素でtimeupdateという名前のイベントを発火する原因となります。
pausedの値をfalseに変更します。
メディア要素タスクをキューに入れ、メディア要素でplayという名前のイベントを発火させます。
メディア要素のreadyState属性の値がHAVE_NOTHING、HAVE_METADATA、またはHAVE_CURRENT_DATAの場合、メディア要素タスクをキューに入れ、waitingという名前のイベントを要素に発生させます。
それ以外の場合、メディア要素のreadyState属性の値がHAVE_FUTURE_DATAまたはHAVE_ENOUGH_DATAである場合、要素に対して再生について通知を行います。
それ以外の場合、メディア要素のreadyState属性の値がHAVE_FUTURE_DATAまたはHAVE_ENOUGH_DATAの場合、保留中の再生プロミスを取得し、メディア要素タスクをキューに入れ、保留中の再生プロミスを解決します。
メディア要素は既に再生中です。ただし、プロミスはキューに入れられたタスクが実行される前に拒否される可能性があります。
pause()メソッドが呼び出されたとき、およびユーザーエージェントがメディア要素を一時停止する必要があるとき、ユーザーエージェントは次の手順を実行する必要があります:
メディア要素のnetworkState属性の値がNETWORK_EMPTYの場合、メディア要素のリソース選択アルゴリズムを呼び出します。
メディア要素に対する内部一時停止手順は次のとおりです:
メディア要素のpaused属性がfalseである場合、次の手順を実行します:
pausedの値をtrueに変更します。
保留中の再生の約束を取得し、promisesをその結果として設定します。
メディア要素タスクをキューに入れ、メディア要素に対して次の手順を実行します:
イベントを発火し、要素に対してtimeupdateという名前のイベントを発生させます。
保留中の再生プロミスをpromisesとerrorで拒否し、"AbortError" DOMExceptionを返します。
要素のplaybackRateが正またはゼロの場合、再生の方向は前方です。それ以外の場合、後方になります。
メディア要素が潜在的に再生中であり、そのドキュメントが完全にアクティブなドキュメントである場合、要素のplaybackRate単位のメディア時間でメディアタイムラインのクロックの1単位時間ごとに、現在の再生位置が単調に増加しなければなりません。(この仕様ではこれを常に「増加」と呼びますが、実際には要素のplaybackRateが負である場合、その増加は減少となることがあります。)
要素のplaybackRateは0.0である可能性があり、その場合現在の再生位置は動かず、再生が一時停止されていないにもかかわらず(pausedがtrueにならず、pauseイベントが発生しません)。
この仕様では、ユーザーエージェントが適切な再生速度をどのように達成するかを定義していません。プロトコルやメディアの状況に応じて、ユーザーエージェントがサーバーと交渉して、サーバーが適切な速度でメディアデータを提供するようにすることが考えられます。したがって、(速度が変更されてからサーバーがストリームの再生速度を更新するまでの期間を除いて)クライアントが実際にフレームを落としたり補間したりする必要はありません。
ユーザーエージェントが安定状態を提供するたびに、公式再生位置を現在の再生位置に設定する必要があります。
再生の方向が後方である間、対応するオーディオはミュートされなければなりません。要素のplaybackRateが非常に低いか高すぎて、ユーザーエージェントがオーディオを有効に再生できない場合も、対応するオーディオはミュートされなければなりません。要素のplaybackRateが1.0でなく、preservesPitchがtrueである場合、ユーザーエージェントは元の音声のピッチを維持するためにピッチ調整を適用する必要があります。それ以外の場合、ユーザーエージェントはピッチ調整なしで音声を速くまたは遅く再生する必要があります。
メディア要素が潜在的に再生中であるとき、その音声データは要素の実効メディア音量で現在の再生位置と同期して再生されなければなりません。ユーザーエージェントは、イベントループが最後にステップ1に到達したときに有効になっていたオーディオトラックから音声を再生しなければなりません。
メディア要素が潜在的に再生中でないとき、要素の音声は再生されてはなりません。
メディア要素が潜在的に再生中であり、ドキュメントに存在しない場合、ビデオは再生してはなりませんが、オーディオコンポーネントは再生する必要があります。すべての参照が削除されたためにメディア要素が再生を停止してはならず、そのメディア要素が今後音声を再生できなくなる状態になった場合にのみ、その要素はガベージコレクションされる可能性があります。
明示的な参照が存在しない要素が音声を再生することは可能です。そのような要素がまだ積極的に再生されていない場合でも、たとえば、一時停止解除されているがコンテンツのバッファリングを待っているか、まだバッファリング中であるが、suspendイベントリスナーが再生を開始する可能性があります。たとえメディアリソースに音声トラックが存在しないメディア要素でも、イベントリスナーがメディアリソースを変更する場合は、再び音声を再生する可能性があります。
各メディア要素には、最初は空である必要がある新しく導入されたキューのリストがあります。テキストトラックキューがキューのリストに追加されるたびに、テキストトラックがメディア要素のテキストトラックのリストに含まれている場合、そのキューはメディア要素の新しく導入されたキューのリストに追加される必要があります。テキストトラックがメディア要素のテキストトラックのリストに追加されるたびに、そのテキストトラックのキューのリストにあるすべてのキューがメディア要素の新しく導入されたキューのリストに追加される必要があります。メディア要素の新しく導入されたキューのリストに新しいキューが追加されたときに、メディア要素のポスター表示フラグが設定されていない場合、ユーザーエージェントは時は進む手順を実行する必要があります。
テキストトラックキューがメディア要素のキューのリストから削除されるとき、またはテキストトラックがメディア要素のテキストトラックのリストから削除されるたびに、メディア要素のポスター表示フラグが設定されていない場合、ユーザーエージェントは時は進む手順を実行する必要があります。
メディア要素の現在の再生位置が変更されるとき(例: 再生やシークによって)、ユーザーエージェントは時は進む手順を実行する必要があります。キューイベントの発火タイミングの精度に依存するユースケース(例: 字幕をビデオのシーン変更と同期させるなど)をサポートするために、ユーザーエージェントはキューイベントをメディアタイムライン上の位置にできるだけ近づけて発火する必要があり、理想的には20ミリ秒以内に発火する必要があります。手順の実行中に現在の再生位置が変更された場合、ユーザーエージェントは手順の完了を待ち、直ちに手順を再実行する必要があります。これらの手順は可能な限り頻繁に、または必要に応じて実行されます。
1回のイテレーションに長い時間がかかると、ユーザーエージェントが「追いつく」ために急いで短時間のキューをスキップすることがあり、そのキューはactiveCuesリストに表示されません。
時は進む手順は次のとおりです:
current cuesをまたはshowing状態のすべてのテキストトラックのすべてのキューを含むように初期化されたリストとし、これには無効なものは含まれません。これらのキューの開始時刻が現在の再生位置以下であり、終了時刻が現在の再生位置よりも大きい場合に限ります。
other cuesをおよびshowing状態のすべてのテキストトラックのすべてのキューを含むように初期化されたリストとし、これにはcurrent cuesには存在しないものを含みます。
last timeを、このアルゴリズムが最後にこのメディア要素のために実行されたときの現在の再生位置とし、これが初めて実行される場合は何も行いません。
通常の再生中に現在の再生位置が通常の単調な増加によってのみ変更された場合、missed cuesを、other cuesに含まれ、開始時刻がlast time以上であり、終了時刻が現在の再生位置以下であるキューのリストとします。それ以外の場合、missed cuesを空のリストとします。
missed cuesに含まれるすべてのキューを削除し、それらがメディア要素の新しく導入されたキューのリストに含まれている場合、そのリストを空にします。
通常の再生中に通常の単調な増加によって時間が達した場合、過去15〜250ミリ秒以内に要素に対してtimeupdateイベントが発生しておらず、そのようなイベントのイベントハンドラがまだ実行中でない場合、ユーザーエージェントはメディア要素タスクをキューに追加し、要素でイベントを発生させ、名前をtimeupdateとします。(他のケース、例えば明示的なシークでは、関連するイベントが現在の再生位置の変更の全体的なプロセスの一部として発生します。)
イベントはこのようにして約66Hz以上または4Hz以下で発生させないようにします(イベントハンドラが250ミリ秒以上かからないことを前提とします)。ユーザーエージェントは、システム負荷や各イベント処理の平均コストに基づいてイベントの発生頻度を調整し、ビデオのデコード中にユーザーエージェントが快適に処理できる頻度を超えないようにすることを推奨します。
current cuesのすべてのキューがテキストトラックキューアクティブフラグを設定されており、other cuesのいずれのキューもテキストトラックキューアクティブフラグを設定されておらず、missed cuesが空である場合、手順を終了します。
通常の再生中に通常の単調な増加によって時間が達し、other cuesにキューが含まれており、それらがテキストトラックキュー一時停止フラグを設定されており、またはそのキューがテキストトラックキューアクティブフラグを設定されている場合、またはmissed cuesに含まれている場合は、即座にメディア要素を一時停止します。
他のケース、例えば明示的なシークでは、キューの終了時刻を超えるときに再生が一時停止されることはありませんが、そのキューがテキストトラックキュー一時停止フラグを設定されている場合でも同様です。
eventsをタスクのリストとして初期化し、最初は空にします。このリスト内の各タスクは、テキストトラック、テキストトラックキュー、および時間に関連付けられ、タスクがキューに追加される前にリストを並べ替えるために使用されます。
affected tracksをテキストトラックのリストとして初期化し、最初は空にします。
以下の手順で、イベントを準備するように指定されたときは、テキストトラックキューのtargetと時間timeに基づいて、ユーザーエージェントは以下の手順を実行する必要があります。
enterとし、TextTrackCueオブジェクトの開始時刻とします。
exitとし、TextTrackCueオブジェクトの終了時刻および開始時刻の遅い方とします。enterとし、TextTrackCueオブジェクトの開始時刻とします。
eventsのタスクを、時間順に昇順で並べ替えます(タスクのうち、時間が早いものを先にします)。
さらに、同じ時間を持つタスクを、そのテキストトラックキューの順序に従って並べ替えます。
最後に、同じ時間と同じテキストトラックキューの順序を持つタスクを、enterイベントを発生させるものを、exitイベントを発生させるものの前に配置します。
affected tracksを、テキストトラックのリスト内でメディア要素が現れる順序で並べ替え、重複を削除します。
affected tracks内の各テキストトラックに対して、リストの順番に、メディア要素タスクをキューに追加し、メディア要素に対して、イベントを発生させ、cuechangeという名前でTextTrackオブジェクトに対して実行します。また、テキストトラックに対応するtrack要素がある場合は、イベントを発生させ、cuechangeという名前でそのtrack要素にも実行します。
affected tracks内でshowing状態にある各テキストトラックのテキストトラックレンダリングを更新するためのルールを実行し、テキストトラックのテキストトラック言語が空でない限り、フォールバック言語として提供します。たとえば、WebVTTに基づくテキストトラックの場合、WebVTTテキストトラックの表示を更新するためのルールを使用します。[WEBVTT]
上記のアルゴリズムにおいて、テキストトラックキューは、単にテキストトラックに関連付けられているだけでなく、テキストトラックのキューリストにリストされている場合にのみ、そのテキストトラックの一部と見なされます。
もしメディア要素のノードドキュメントが完全にアクティブなドキュメントでなくなった場合、ドキュメントが再びアクティブになるまで、再生が停止します。
メディア要素がドキュメントから削除された場合、ユーザーエージェントは次のステップを実行する必要があります:
安定した状態を待つことにより、タスクがメディア要素をドキュメントから削除することを続行させます。このアルゴリズムの残りのステップはすべて同期セクションで構成されます。(同期セクション内のステップは⌛で示されます。)
⌛ メディア要素がドキュメント内にある場合、リターンします。
media.seeking
ユーザーエージェントが現在シーク中の場合、trueを返します。
media.seekable
すべての現行エンジンでサポートされています。
ユーザーエージェントがシーク可能なメディアリソースの範囲を表すTimeRangesオブジェクトを返します。
media.fastSeek(time)
できるだけ早く、新しいtimeにシークし、精度をスピードに交換します。(正確な時間にシークするには、currentTime属性を使用してください。)
メディアリソースが読み込まれていない場合は、何も行いません。
seeking属性の初期値はfalseでなければなりません。
fastSeek(time)メソッドは、timeで与えられた時間にシークし、
approximate-for-speedフラグが設定されます。
ユーザーエージェントが特定の新しい再生位置にシークする必要がある場合、 任意でapproximate-for-speedフラグが設定されている場合、ユーザーエージェントは次の手順を実行しなければなりません。 このアルゴリズムは、イベントループメカニズムと密接に関係しています。特に、同期セクション(イベントループ アルゴリズムの一部としてトリガーされる)を含んでいます。このセクションのステップは、⌛でマークされています。
要素のreadyStateがHAVE_NOTHINGである場合、戻ります。
要素のseekingIDL属性がtrueである場合、
このアルゴリズムの他のインスタンスがすでに実行されています。そのインスタンスを、実行中のステップを完了するのを待たずに中止します。
seekingIDL属性をtrueに設定します。
シークがDOMメソッド呼び出しまたはIDL属性の設定に応じて行われた場合、スクリプトの実行を続行します。これらのステップの残りは並行して実行されなければなりません。⌛でマークされたステップを除いて、このアルゴリズムの別のインスタンスが呼び出された場合、いつでも中止される可能性があります。
新しい再生位置がメディアリソースの終わりより後である場合、 それをメディアリソースの終わりにします。
新しい再生位置が最も早い位置より前である場合、 それをその位置に設定します。
(おそらく変更された)新しい再生位置がseekable属性で示される範囲内にない場合、
それをseekable属性で示される範囲内の
新しい再生位置に最も近い位置にします。この条件を満たす2つの位置がある場合(つまり、新しい再生位置がseekable属性の2つの範囲のちょうど中間にある場合)、
現在の再生位置に最も近い位置を使用します。seekable属性に範囲がない場合、seekingIDL属性をfalseに設定し、戻ります。
approximate-for-speedフラグが設定されている場合、新しい再生位置を再生がすぐに再開できるような値に調整します。新しい再生位置がこのステップの前に現在の再生位置より前である場合、調整された新しい再生位置も現在の再生位置より前でなければなりません。同様に、新しい再生位置がこのステップの前に現在の再生位置より後である場合、調整された新しい再生位置も現在の再生位置より後でなければなりません。
例えば、ユーザーエージェントは、再生を再開する前に中間フレームをデコードして破棄する時間を省くために、近くのキーフレームにスナップすることができます。
メディア要素タスクをキューに追加する
メディア要素に対して、イベントを発生させる名seekingを発火させます。
現在の再生位置を新しい再生位置に設定します。
メディア要素が潜在的に再生中だったが、シークによってそのreadyState属性がHAVE_FUTURE_DATAより低い値に変更された場合、waitingイベントが要素に対して発火されます。
このステップは現在の再生位置を設定します。したがって、ユーザーエージェントが実際にその位置のメディアデータをレンダリングできるかどうかにかかわらず、(次のステップで決定されるように)他の条件、たとえば再生が「メディアリソースの終わりに達する」に関するルールなどが直ちにトリガーされる可能性があります(ループ処理のロジックの一部として)。
currentTime属性は公式の再生位置を返し、現在の再生位置を返すわけではありません。そのため、このアルゴリズムとは別に、スクリプトの実行前に更新されます。
ユーザーエージェントが新しい再生位置のメディアデータが利用可能かどうかを確認し、利用可能であれば、その位置を再生するのに十分なデータがデコードされるまで待機します。
安定した状態を待機します。同期セクションはこのアルゴリズムの残りのすべてのステップで構成されます。(同期セクションのステップは⌛でマークされています。)
⌛seekingIDL属性をfalseに設定します。
⌛時間は進み続けるステップを実行します。
⌛メディア要素タスクをキューに追加する
メディア要素に対して、イベントを発生させる名timeupdateを発火させます。
⌛メディア要素タスクをキューに追加する
メディア要素に対して、イベントを発生させる名seekedを発火させます。
seekable属性は、新しい静的な正規化TimeRangesオブジェクトを返さなければなりません。これは、ユーザーエージェントがシークできるメディアリソースの範囲を表します。この属性が評価される時点で存在する場合に限ります。
ユーザーエージェントがメディアリソースのどこにでもシークできる場合、例えば、単純な映画ファイルであり、ユーザーエージェントとサーバーがHTTP
Rangeリクエストをサポートしている場合、この属性は1つの範囲を持つオブジェクトを返します。その開始は最初のフレームの時間(通常はゼロである最も早い位置)であり、その終了は最初のフレームの時間にduration属性の値を加えたものと等しく(最終フレームの時間に等しく、正の無限大である可能性もあります)。
範囲は連続して変化することがあります。例えば、ユーザーエージェントが無限ストリームでスライディングウィンドウをバッファリングしている場合です。これは、DVRがライブTVを視聴する際に見られる動作です。
毎回新しいオブジェクトを返すことは、属性ゲッターにとって悪いパターンであり、ここでのみ、それを変更するのにコストがかかるために記載されています。新しいAPIにコピーするべきではありません。
ユーザーエージェントは、シーク可能な範囲に対して非常に寛容で楽観的な見方を採用するべきです。ユーザーエージェントは、可能な限りシークを迅速に行うために、最近のコンテンツをバッファリングするべきです。
例えば、HTTP RangeリクエストをサポートしないHTTPサーバーで提供される大きなビデオファイルを考えてみてください。ブラウザは、現在のフレームとその後のフレームのデータだけをバッファリングし、シークを許可しない(再生の最初に戻るシークを除く)ことによってこれを実装できます。しかし、これは質の低い実装です。質の高い実装では、ユーザーが何か驚くべきことを再視聴するために即座に戻ることができるように、(または十分なストレージがあればもっと長く)コンテンツの最後の数分をバッファリングし、必要に応じてファイルを再読み込みすることで任意の場所にシークすることを可能にするべきです。これにより速度が遅くなる可能性がありますが、ビデオを最初から再開し、再生されていない部分に到達するためだけに全体を視聴し直すよりも、はるかに便利です。
メディアリソースは内部でスクリプト化されているか、インタラクティブな場合があります。このため、メディア要素は非線形的に再生される可能性があります。この場合、ユーザーエージェントは、シークアルゴリズムが使用されたかのように動作しなければならず、現在の再生位置が不連続に変更されるたびに関連するイベントが発火します。
メディアリソースには、複数の埋め込みオーディオおよびビデオトラックが含まれる場合があります。たとえば、主要なビデオおよびオーディオトラックに加えて、メディアリソースには、外国語の吹き替え、監督のコメント、音声説明、別のアングル、または手話のオーバーレイが含まれる場合があります。
media.audioTracks
すべての現行エンジンでサポートされています。
AudioTrackListオブジェクトを返します。このオブジェクトは、メディアリソースで利用可能なオーディオトラックを表します。
media.videoTracks
すべての現行エンジンでサポートされています。
VideoTrackListオブジェクトを返します。このオブジェクトは、メディアリソースで利用可能なビデオトラックを表します。
メディア要素のaudioTracks属性は、ライブのAudioTrackListオブジェクトを返さなければなりません。このオブジェクトは、メディア要素のメディアリソースで利用可能なオーディオトラックを表します。
メディア要素のvideoTracks属性は、ライブのVideoTrackListオブジェクトを返さなければなりません。このオブジェクトは、メディア要素のメディアリソースで利用可能なビデオトラックを表します。
1つのメディア要素につき、1つのAudioTrackListオブジェクトと1つのVideoTrackListオブジェクトのみが存在します。別のメディアリソースが要素にロードされた場合でも、オブジェクトは再利用されます。(ただし、AudioTrackオブジェクトやVideoTrackオブジェクトは再利用されません。)
AudioTrackList
および VideoTrackList
オブジェクトすべての現行エンジンでサポートされています。
すべての現行エンジンでサポートされています。
AudioTrackList
およびVideoTrackList
インターフェースは、前のセクションで定義された属性によって使用されます。
すべての現行エンジンでサポートされています。
すべての現行エンジンでサポートされています。
[Exposed =Window ]
interface AudioTrackList : EventTarget {
readonly attribute unsigned long length ;
getter AudioTrack (unsigned long index );
AudioTrack ? getTrackById (DOMString id );
attribute EventHandler onchange ;
attribute EventHandler onaddtrack ;
attribute EventHandler onremovetrack ;
};
[Exposed =Window ]
interface AudioTrack {
readonly attribute DOMString id ;
readonly attribute DOMString kind ;
readonly attribute DOMString label ;
readonly attribute DOMString language ;
attribute boolean enabled ;
};
[Exposed =Window ]
interface VideoTrackList : EventTarget {
readonly attribute unsigned long length ;
getter VideoTrack (unsigned long index );
VideoTrack ? getTrackById (DOMString id );
readonly attribute long selectedIndex ;
attribute EventHandler onchange ;
attribute EventHandler onaddtrack ;
attribute EventHandler onremovetrack ;
};
[Exposed =Window ]
interface VideoTrack {
readonly attribute DOMString id ;
readonly attribute DOMString kind ;
readonly attribute DOMString label ;
readonly attribute DOMString language ;
attribute boolean selected ;
};
media.audioTracks.length
すべての現行エンジンでサポートされています。
media.videoTracks.length
すべての現行エンジンでサポートされています。
リスト内のトラックの数を返します。
audioTrack = media.audioTracks[index]
videoTrack = media.videoTracks[index]
指定されたAudioTrack
またはVideoTrackオブジェクトを返します。
audioTrack = media.audioTracks.getTrackById(id)
すべての現行エンジンでサポートされています。
videoTrack = media.videoTracks.getTrackById(id)
すべての現行エンジンでサポートされています。
指定されたIDを持つAudioTrack
またはVideoTrackオブジェクトを返します。トラックにそのIDがない場合はnullを返します。
audioTrack.id
すべての現行エンジンでサポートされています。
videoTrack.id
すべての現行エンジンでサポートされています。
指定されたトラックのIDを返します。これは、フォーマットがメディアフラグメント構文をサポートしている場合にフラグメントに使用でき、getTrackById()メソッドで使用できます。
audioTrack.kind
すべての現行エンジンでサポートされています。
videoTrack.kind
すべての現行エンジンでサポートされています。
指定されたトラックのカテゴリを返します。考えられるトラックカテゴリは下記に示されています。
audioTrack.label
すべての現行エンジンでサポートされています。
videoTrack.label
すべての現行エンジンでサポートされています。
指定されたトラックのラベルが既知の場合はラベルを、そうでない場合は空文字列を返します。
audioTrack.language
すべての現行エンジンでサポートされています。
videoTrack.language
すべての現行エンジンでサポートされています。
指定されたトラックの言語を返します。既知の場合は言語を、そうでない場合は空文字列を返します。
audioTrack.enabled [ = value ]
すべての現行エンジンでサポートされています。
指定されたトラックがアクティブであればtrueを返し、そうでなければfalseを返します。
設定することにより、トラックが有効かどうかを変更できます。複数のオーディオトラックが同時に有効になっている場合、それらはミックスされます。
media.videoTracks.selectedIndex
すべての現行エンジンでサポートされています。
現在選択されているトラックのインデックスを返し、そうでなければ−1を返します。
videoTrack.selected [ = value ]
すべての現行エンジンでサポートされています。
指定されたトラックがアクティブであればtrueを返し、そうでなければfalseを返します。
設定することにより、トラックが選択されているかどうかを変更できます。選択されたトラックが1つだけであり、前のトラックが選択されている場合、新しいトラックを選択すると前のトラックが選択解除されます。
AudioTrackList
オブジェクトは、ゼロまたはそれ以上のオーディオトラックの動的リストを表し、そのうちゼロまたは複数が同時に有効にできます。各オーディオトラックは、AudioTrackオブジェクトで表されます。
VideoTrackList
オブジェクトは、ゼロまたはそれ以上のビデオトラックの動的リストを表し、そのうちゼロまたは1つが同時に選択できます。各ビデオトラックは、VideoTrackオブジェクトで表されます。
AudioTrackListとVideoTrackListオブジェクト内のトラックは、一貫して順序付けられている必要があります。メディアリソースが順序を定義する形式である場合は、その順序を使用しなければなりません。そうでない場合は、トラックがメディアリソース内で宣言された相対的な順序が使用されなければなりません。使用される順序は、リストの自然順序と呼ばれます。
これらのオブジェクト内の各トラックにはインデックスが付与され、最初のトラックはインデックス0を持ち、次の各トラックは前のものよりも1つ高い番号が付けられます。メディアリソースが動的にオーディオまたはビデオトラックを追加または削除すると、トラックのインデックスは動的に変更されます。メディアリソースが完全に変更される場合、以前のすべてのトラックが削除され、新しいトラックに置き換えられます。
AudioTrackListとVideoTrackListのlength属性ゲッターは、取得時にそのオブジェクトが表すトラックの数を返す必要があります。
サポートされているプロパティインデックスは、その瞬間にAudioTrackListとVideoTrackListオブジェクトが表すトラックの数から1を引いた数までの数字です。もしAudioTrackListまたはVideoTrackListオブジェクトがトラックを表していない場合、それはサポートされているプロパティインデックスを持っていません。
インデックスプロパティの値を決定するには、指定されたindexに対してAudioTrackListまたはVideoTrackListオブジェクト内のトラックをlistから取得する必要があります。ユーザーエージェントは、そのindexに対応するAudioTrackまたはVideoTrackオブジェクトを返す必要があります。
AudioTrackListとVideoTrackListのgetTrackById(id)メソッドは、id引数の値と一致する最初のAudioTrackまたはVideoTrackオブジェクト(それぞれ)を返す必要があります。引数に一致するトラックがない場合、メソッドはnullを返す必要があります。
AudioTrackおよびVideoTrackオブジェクトは、メディアリソースの特定のトラックを表します。各トラックには、識別子、カテゴリ、ラベル、言語が付与されることがあります。これらのトラックの特性は、トラックの存続期間中は変わりません。たとえトラックがAudioTrackListまたはVideoTrackListオブジェクトから削除されても、これらの特性は変更されません。
また、AudioTrackオブジェクトは、それぞれ有効または無効にできます。これはオーディオトラックの有効状態です。AudioTrackが作成されると、その有効状態はfalse(無効)に設定される必要があります。リソースフェッチアルゴリズムがこれを上書きすることができます。
同様に、VideoTrackオブジェクトはVideoTrackListオブジェクト内で一つだけ選択されることができます。これはビデオトラックの選択状態です。VideoTrackが作成されると、その選択状態はfalse(未選択)に設定される必要があります。リソースフェッチアルゴリズムがこれを上書きすることができます。
AudioTrackのid属性およびVideoTrackのid属性は、トラックに識別子がある場合はその識別子を、ない場合は空の文字列を返さなければなりません。メディアリソースがメディアフラグメント構文をサポートしている形式の場合、特定のトラックに対して返される識別子は、そのようなフラグメントのトラック次元におけるトラック名として使用された場合に、そのトラックを有効にするのと同じ識別子でなければなりません。[INBAND]
例えば、Oggファイルでは、これはトラックのNameヘッダーフィールドになります。[OGGSKELETONHEADERS]
AudioTrackとVideoTrackのkind属性は、そのトラックのカテゴリを返す必要があり、そうでない場合は空の文字列を返す必要があります。
トラックのカテゴリは、以下の表の最初の列にある文字列で、そのトラックに最も適しているものです。表の第2および第3列の定義に基づいて判断され、メディアリソースに含まれるメタデータによって決定されます。表の第3列にあるセルは、その列の最初の列にあるカテゴリがどのトラックに適用されるかを示します。カテゴリは、オーディオトラックに適用される場合にのみオーディオトラックに適しており、ビデオトラックに適用される場合にのみビデオトラックに適しています。カテゴリは、AudioTrackオブジェクトに適している場合にのみ返されるべきであり、VideoTrackオブジェクトに適している場合にのみ返されるべきです。
Oggファイルの場合、トラックのRoleヘッダーフィールドが関連するメタデータを提供します。DASHメディアリソースの場合、Role要素が情報を伝えます。WebMの場合、現在はFlagDefault要素のみが値にマッピングされます。HTMLへのメディアコンテナからのインバンドメディアリソーストラックのソーシングには詳細が記載されています。[OGGSKELETONHEADERS] [DASH] [WEBMCG] [INBAND]
| カテゴリ | 定義 | 適用範囲 | 例 |
|---|---|---|---|
"alternative" |
メイントラックの代替可能なトラック、例: 別テイクの曲(オーディオ)や別の角度(ビデオ)。 | オーディオおよびビデオ。 | Ogg: "audio/alternate" または "video/alternate";DASH: "main" および "commentary" 役割がない "alternate"、およびオーディオの場合は "dub" 役割がないもの(他の役割は無視)。 |
"captions" |
字幕が焼き付けられたメインビデオトラックのバージョン。(レガシーコンテンツ用;新しいコンテンツはテキストトラックを使用する)。 | ビデオのみ。 | DASH: "caption" および "main" 役割が一緒に(他の役割は無視)。 |
"descriptions" |
ビデオトラックのオーディオディスクリプション。 | オーディオのみ。 | Ogg: "audio/audiodesc"。 |
"main" |
主要なオーディオまたはビデオトラック。 | オーディオおよびビデオ。 | Ogg: "audio/main" または "video/main";WebM: "FlagDefault" 要素が設定されている;DASH: "caption"、"subtitle"、および "dub" 役割がない "main" 役割(他の役割は無視)。 |
"main-desc" |
オーディオディスクリプションが混ざった主要なオーディオトラック。 | オーディオのみ。 | MPEG-2 TS のAC3オーディオ: bsmod=2 および full_svc=1。 |
"sign" |
オーディオトラックの手話通訳。 | ビデオのみ。 | Ogg: "video/sign"。 |
"subtitles" |
字幕が焼き付けられたメインビデオトラックのバージョン。(レガシーコンテンツ用;新しいコンテンツはテキストトラックを使用する)。 | ビデオのみ。 | DASH: "subtitle" および "main" 役割が一緒に(他の役割は無視)。 |
"translation" |
主要なオーディオトラックの翻訳版。 | オーディオのみ。 | Ogg: "audio/dub"。DASH: "dub" および "main" 役割が一緒に(他の役割は無視)。 |
"commentary" |
主要なオーディオまたはビデオトラックの解説、例: 監督の解説。 | オーディオおよびビデオ。 | DASH: "main" 役割がない "commentary" 役割(他の役割は無視)。 |
""(空文字列) |
明示的な種類がないか、トラックのメタデータで指定された種類がユーザーエージェントによって認識されない。 | オーディオおよびビデオ。 |
AudioTrackとVideoTrackのlabelおよびlabel属性は、トラックにラベルがある場合はそのラベルを返し、そうでない場合は空の文字列を返す必要があります。[INBAND]
AudioTrackとVideoTrackのlanguageおよびlanguage属性は、トラックの言語がある場合はその言語のBCP
47言語タグを返し、そうでない場合は空の文字列を返す必要があります。ユーザーエージェントがその言語をBCP 47言語タグとして表現できない場合(例えば、メディアリソースの形式内の言語情報が解釈が定義されていない自由形式の文字列である場合など)、そのメソッドは、トラックに言語がないかのように空の文字列を返す必要があります。[INBAND]
AudioTrackのenabled属性は、取得時にトラックが現在有効であればtrueを返し、そうでなければfalseを返す必要があります。設定時には、新しい値がtrueであればトラックを有効にし、それ以外の場合は無効にする必要があります。(トラックがAudioTrackListオブジェクトにもう存在しない場合、トラックが有効または無効になってもAudioTrackオブジェクトの属性値を変更すること以外には影響がありません。)
AudioTrackList内のオーディオトラックが無効から有効になった場合、または有効から無効になった場合、ユーザーエージェントはメディア要素タスクをキューに追加する必要があり、AudioTrackListオブジェクトでchangeという名前のイベントを発火する必要があります。
特定の位置にデータが存在しないか、その位置に存在しないオーディオトラックは、そのタイムラインのポイントで無音と見なされる必要があります。
VideoTrackListのselectedIndex属性は、現在選択されているトラックのインデックスを返す必要があります。VideoTrackListオブジェクトが現在トラックを表していない場合、またはトラックが選択されていない場合、代わりに−1を返す必要があります。
VideoTrackのselected属性は、取得時にトラックが現在選択されている場合はtrueを返し、そうでない場合はfalseを返す必要があります。設定時には、新しい値がtrueであればトラックを選択し、それ以外の場合は選択を解除する必要があります。トラックがVideoTrackListに含まれている場合、そのリスト内の他のすべてのVideoTrackオブジェクトは選択解除される必要があります。(トラックがVideoTrackListオブジェクトにもう存在しない場合、トラックが選択または非選択になってもVideoTrackオブジェクトの属性値を変更すること以外には影響がありません。)
VideoTrackList内の以前選択されていなかったトラックが選択された場合、およびVideoTrackList内の選択されたトラックが、新しいトラックが代わりに選択されないまま非選択になった場合、ユーザーエージェントはメディア要素タスクをキューに追加する必要があり、VideoTrackListオブジェクトでchangeという名前のイベントを発火する必要があります。このタスクは、resizeイベントを発火させるタスクの前にキューに追加される必要があります。
特定の位置にデータが存在しないビデオトラックは、そのタイムラインのポイントで透明な黒として解釈される必要があり、その位置の直前のフレームと同じ寸法、またはその位置がそのトラックのすべてのデータよりも前である場合はそのトラックの最初のフレームと同じ寸法を持つ必要があります。現在の位置にまったく存在しないトラックは、存在するがデータがないかのように扱われる必要があります。
例えば、ビデオに再生開始から1時間後にのみ導入されるトラックがあり、ユーザーがそのトラックを選択してから開始時点に戻ると、ユーザーエージェントはそのトラックがメディアリソースの開始時点から始まっていたかのように振る舞い、1時間経過するまで単に透明であったかのように扱います。
次に示すのは、イベントハンドラー(およびそれに対応するイベントハンドラーイベントタイプ)であり、イベントハンドラーIDL属性として、AudioTrackListおよびVideoTrackListインターフェースを実装するすべてのオブジェクトによってサポートされなければなりません:
| イベントハンドラー | イベントハンドラーイベントタイプ |
|---|---|
onchange
すべての現在のエンジンでサポートされています。
Firefox🔰 33+
Safari7+
Chrome🔰 37+
Opera? Edge🔰 79+ Edge (Legacy)No Internet Explorer10+ Firefox Android? Safari iOS? Chrome Android? WebView Android? Samsung Internet? Opera Android? すべての現在のエンジンでサポートされています。
Firefox31+
Safari7+
Chrome33+
Opera? Edge79+ Edge (Legacy)18 Internet ExplorerNo Firefox Android? Safari iOS? Chrome Android? WebView Android4.4+ Samsung Internet? Opera Android? すべての現在のエンジンでサポートされています。
Firefox🔰 33+
Safari7+
Chrome🔰 37+
Opera? Edge🔰 79+ Edge (Legacy)No Internet Explorer10+ Firefox Android? Safari iOS? Chrome Android? WebView Android? Samsung Internet? Opera Android? |
change
|
onaddtrack
すべての現在のエンジンでサポートされています。
Firefox🔰 33+
Safari7+
Chrome🔰 37+
Opera? Edge🔰 79+ Edge (Legacy)No Internet Explorer10+ Firefox Android? Safari iOS? Chrome Android? WebView Android? Samsung Internet? Opera Android? すべての現在のエンジンでサポートされています。
Firefox31+
Safari6+
Chrome23+
Opera12.1+ Edge79+ Edge (Legacy)12+ Internet Explorer11 Firefox Android? Safari iOS7+ Chrome Android? WebView Android? Samsung Internet? Opera Android12.1+ すべての現在のエンジンでサポートされています。
Firefox🔰 33+
Safari7+
Chrome🔰 37+
Opera? Edge🔰 79+ Edge (Legacy)No Internet Explorer10+ Firefox Android? Safari iOS? Chrome Android? WebView Android? Samsung Internet? Opera Android? |
addtrack
|
onremovetrack
AudioTrackList/removetrack_event すべての現在のエンジンでサポートされています。
Firefox🔰 33+
Safari7+
Chrome🔰 37+
Opera? Edge🔰 79+ Edge (Legacy)No Internet Explorer10+ Firefox Android? Safari iOS? Chrome Android? WebView Android? Samsung Internet? Opera Android? TextTrackList/removetrack_event すべての現在のエンジンでサポートされています。
Firefox31+
Safari7+
Chrome33+
Opera20+ Edge79+ Edge (Legacy)18 Internet ExplorerNo Firefox Android? Safari iOS? Chrome Android? WebView Android4.4+ Samsung Internet? Opera Android20+ VideoTrackList/removetrack_event すべての現在のエンジンでサポートされています。
Firefox🔰 33+
Safari7+
Chrome🔰 37+
Opera? Edge🔰 79+ Edge (Legacy)No Internet Explorer10+ Firefox Android? Safari iOS? Chrome Android? WebView Android? Samsung Internet? Opera Android? |
removetrack
|
audioTracksおよびvideoTracks属性を使用して、スクリプトで再生するトラックを選択できますが、フラグメントを指定することで、URLのメディアリソースの特定のトラックを宣言的に選択することも可能です。フラグメントの形式は、MIMEタイプによって異なります。メディアリソース。[RFC2046] [URL]
この例では、メディアフラグメント構文をサポートする形式を使用するビデオが埋め込まれており、デフォルトのビデオトラックの代わりに「Alternative」とラベル付けされた別のアングルが有効になっています。
< video src = "myvideo#track=Alternative" ></ video >
メディア要素には、テキストトラックと呼ばれる関連するテキストトラックのグループが含まれることがあります。これらはメディア要素のテキストトラックのリストとして知られています。テキストトラックは次のように並べ替えられます:
テキストトラックは、addTextTrack()メソッドを使用して追加され、追加された順に古いものから新しいものへと並べ替えられます。
メディアリソース固有のテキストトラック(テキストトラックはメディアリソース内のデータに対応するもの)で、メディアリソースのフォーマット仕様によって定義された順序で並べ替えられます。
テキストトラックは以下の要素で構成されます:
この要素はユーザーエージェントがトラックをどのように処理するかを決定します。種類は文字列で表され、可能な文字列は次のとおりです:
subtitlescaptionsdescriptionschaptersmetadataこれは、ユーザーがトラックを識別するための人間が読みやすい文字列です。
トラックのラベルは、テキストトラックがtrack要素に対応する場合、動的に変更されることがあります。
テキストトラックのラベルが空文字列である場合、ユーザーエージェントは、テキストトラックの他のプロパティ(例: テキストトラックの種類や言語)から自動的に適切なラベルを生成して、ユーザーインターフェースで使用する必要があります。この自動生成されたラベルはAPIに公開されません。
これは、インバンドメタデータトラック用にメディアリソースから抽出された文字列で、これにより、これらのトラックがドキュメント内の異なるスクリプトにディスパッチされるようになります。
例えば、ウェブでストリーミングされる従来のテレビ局の放送に、ウェブ固有のインタラクティブな機能が追加されている場合、メタデータを含むテキストトラックには、広告ターゲティング、ゲームショー中のトリビアゲームデータ、スポーツゲーム中のプレイヤーの状態、料理番組中のレシピ情報などが含まれることがあります。各プログラムが開始および終了すると、新しいトラックがストリームに追加されたり削除されたりする可能性があり、それらが追加されると、ユーザーエージェントはこの属性の値を使用して、専用のスクリプトモジュールにバインドすることができます。
インバンドメタデータテキストトラック以外の場合、インバンドメタデータトラックディスパッチタイプは空文字列です。さまざまなメディア形式に対してこの値がどのように設定されるかについては、メディアリソース固有のテキストトラックを公開する手順で説明されています。
これは、テキストトラックのキューの言語を表す文字列(BCP 47言語タグ)です。[BCP47]
テキストトラックの言語は、テキストトラックがtrack要素に対応する場合、動的に変更されることがあります。
次のいずれかです:
テキストトラックのキューが取得されていないことを示します。
テキストトラックがロード中であり、これまでに致命的なエラーは発生していないことを示します。トラックには、パーサーによってさらにキューが追加される可能性があります。
テキストトラックが致命的なエラーなしでロードされたことを示します。
テキストトラックが有効化されたが、ユーザーエージェントがこれを取得しようとした際に何らかの方法で失敗したことを示します(例:URLが解析できなかった、ネットワークエラー、不明なテキストトラック形式など)。キューの一部または全体が欠落しており、取得されることはありません。
テキストトラックの準備状態は、トラックの取得に伴い動的に変化します。
次のいずれかです:
テキストトラックがアクティブでないことを示します。トラックをDOMに公開する目的以外では、ユーザーエージェントはテキストトラックを無視します。キューはアクティブにならず、イベントも発生せず、ユーザーエージェントはトラックのキューを取得しようとしません。
テキストトラックがアクティブであるが、ユーザーエージェントがキューを積極的に表示していないことを示します。トラックのキューを取得しようとしたことがない場合、ユーザーエージェントは間もなくその試みを行います。ユーザーエージェントはアクティブなキューのリストを維持しており、イベントが適切に発生します。
テキストトラックがアクティブであることを示します。トラックのキューを取得しようとしたことがない場合、ユーザーエージェントは間もなくその試みを行います。ユーザーエージェントはアクティブなキューのリストを維持しており、イベントが適切に発生します。さらに、トラックの種類がsubtitlesまたはcaptionsであるテキストトラックの場合、キューは適切にビデオにオーバーレイされます。トラックの種類がdescriptionsであるテキストトラックの場合、ユーザーエージェントはキューを視覚的でない方法でユーザーに提供します。トラックの種類がchaptersであるテキストトラックの場合、ユーザーエージェントはユーザーがキューを選択してメディアリソース内の任意のポイントに移動できるメカニズムを提供します。
これは、テキストトラックキューのリストであり、テキストトラックレンダリングの更新ルールも含まれます。例えば、WebVTTでは、WebVTTテキストトラックの表示を更新するためのルールなどです。[WEBVTT]
テキストトラックのキューのリストは動的に変化することがあります。例えば、テキストトラックがまだロードされていない場合や、ロード中である場合、またはDOM操作による場合です。
各テキストトラックには、対応するTextTrackオブジェクトがあります。
各メディア要素には、保留中のテキストトラックのリストが含まれており、最初は空である必要があります。また、パーサーによってブロックされたフラグも含まれており、最初はfalseに設定されている必要があります。さらに、自動トラック選択を実行したかどうかのフラグも含まれており、これも最初はfalseに設定されている必要があります。
ユーザーエージェントが保留中のテキストトラックのリストを設定する必要があるとき、ユーザーエージェントは、メディア要素の保留中のテキストトラックのリストに、その要素のテキストトラックのリストに含まれる各テキストトラックを追加しなければなりません。その際、テキストトラックモードが無効でなく、テキストトラックの準備状態が読み込み中である必要があります。
要素の親ノードが変更されるたびに、ユーザーエージェントは、対応するテキストトラックを、含まれている保留中のテキストトラックのリストから削除する必要があります。
テキストトラックのテキストトラックの準備状態がロード済みまたはロードに失敗のいずれかに変更されるたびに、ユーザーエージェントはそのトラックを含まれている保留中のテキストトラックのリストから削除する必要があります。
メディア要素がHTMLパーサーまたはXMLパーサーによって作成されると、ユーザーエージェントはその要素のパーサーによってブロックされたフラグをtrueに設定する必要があります。メディア要素がHTMLパーサーまたはXMLパーサーのスタックからポップオフされると、ユーザーエージェントはユーザーの自動テキストトラック選択に関する設定を尊重し、保留中のテキストトラックのリストを埋める必要があり、要素のパーサーによってブロックされたフラグをfalseに設定する必要があります。
テキストトラックがメディア要素の準備が整っている状態になるのは、要素の保留中のテキストトラックのリストが空であり、要素のパーサーによってブロックされたフラグがfalseである場合です。
各メディア要素には、保留中のテキストトラック変更通知フラグが含まれており、最初はリセットされている必要があります。
テキストトラックがメディア要素のテキストトラックのリストに含まれている場合、そのテキストトラックモードが変更された場合、ユーザーエージェントは次の手順を実行する必要があります:
メディア要素の保留中のテキストトラック変更通知フラグが設定されている場合、リターンします。
メディア要素の保留中のテキストトラック変更通知フラグを設定します。
メディア要素タスクをキューに追加し、次の手順を実行します:
メディア要素の保留中のテキストトラック変更通知フラグをリセットします。
イベントを発生させる、イベント名はchangeで、メディア要素のtextTracks属性のTextTrackListオブジェクトで発生します。
メディア要素のポスターフラグを表示するが設定されていない場合、時間が進行する手順を実行します。
このセクションに記載されているタスクのタスクソースは、DOM操作タスクソースです。
テキストトラックキューは、テキストトラック内の時間に敏感なデータの単位であり、たとえば、字幕やキャプションにおいて、特定の時間に表示され、別の時間に消えるテキストに対応します。
各テキストトラックキューは以下で構成されます:
任意の文字列です。
メディアデータのどの範囲にキューが適用されるかを示す時間(秒および秒の小数部)です。
メディアデータのどの範囲にキューが適用されるかを示す時間(秒および秒の小数部)です。ただし、無制限のテキストトラックキューの場合は正の無限大になります。
キューが適用される範囲の終了時にメディアリソースの再生を一時停止するかどうかを示すブール値です。
フォーマットに必要な追加フィールド、およびキューの実際のデータが含まれます。たとえば、WebVTTにはテキストトラックキューの書字方向などがあります。[WEBVTT]
無制限のテキストトラックキューは、終了時間が正の無限大に設定されたテキストトラックキューです。アクティブな無制限のテキストトラックキューは、通常の再生中に現在の再生位置の単調な増加によって非アクティブになることはありません(例: 終了時間が発表されていないライブイベントのチャプター用のメタデータキュー)。
テキストトラックキューの開始時間およびテキストトラックキューの終了時間は負の値である場合があります。(ただし、現在の再生位置は負の値になることはないため、ゼロ時点前のキューはアクティブにはなりません。)
各テキストトラックキューには、対応するTextTrackCueオブジェクト(または、TextTrackCueから継承されたオブジェクト、例えばWebVTTキューはVTTCueインターフェースを使用)があります。テキストトラックキューのメモリ内表現は、このTextTrackCueAPIを介して動的に変更することができます。[WEBVTT]
テキストトラックキューは、特定の種類のテキストトラックキューに対して仕様で定義されたテキストトラックレンダリングを更新するためのルールに関連付けられています。これらのルールは、キューを表すオブジェクトがTextTrackオブジェクトにaddCue()メソッドを使用して追加されたときに特に使用されます。
さらに、各テキストトラックキューには、2つの動的な情報があります:
このフラグは最初はリセットされています。フラグは、キューがアクティブまたは非アクティブになったときに適切にイベントが発生するようにし、適切なキューがレンダリングされるようにするために使用されます。
ユーザーエージェントは、このフラグを次のタイミングで同期的にリセットする必要があります: テキストトラックキューがそのテキストトラックのテキストトラックのキューリストから削除された場合、テキストトラック自体がそのメディア要素のテキストトラックリストから削除された場合、またはテキストトラックモードが無効に変更された場合、さらに、メディア要素のreadyStateが再度HAVE_NOTHINGに変更された場合です。この方法でフラグが1つ以上のテキストトラックのキューに対してリセットされた場合、ユーザーエージェントは、影響を受けたすべてのキューのフラグをリセットした後、それらのテキストトラックのテキストトラックレンダリングを更新するためのルールを適用する必要があります。たとえば、WebVTTベースのテキストトラックの場合、WebVTTテキストトラックの表示を更新するためのルールなどです。[WEBVTT]
これはレンダリングモデルの一部として使用され、キューを一貫した位置に保ちます。最初は空です。テキストトラックキューアクティブフラグがリセットされるたびに、ユーザーエージェントはテキストトラックキュー表示状態を空にする必要があります。
テキストトラックキューは、メディア要素のテキストトラックに属しており、これらのキューはテキストトラックキューの順序で相互に並べ替えられます。この順序は次のように決定されます: 最初にキューをテキストトラックごとにグループ化し、グループはそのテキストトラックがメディア要素のテキストトラックのリストに現れる順序で並べ替えられます。その後、各グループ内でキューは、その開始時間に従って並べ替えられ、最も早いものが最初に並べ替えられます。その後、同じ開始時間を持つキューは、その終了時間に従って並べ替えられ、最も遅いものが最初に並べ替えられます。最後に、同じ終了時間を持つキューは、それぞれが最後にテキストトラックのキューリストに追加された順序で並べ替えられ、最も古いものが最初になります(たとえば、WebVTTファイルからのキューの場合、最初はファイルに記載された順序になります)。[WEBVTT]
メディアリソース固有のテキストトラックは、テキストトラックであり、 メディアリソースに含まれるデータに対応します。
そのようなデータの処理とレンダリングのルールは、関連する仕様、例えばメディアリソースがビデオである場合にはビデオフォーマットの仕様によって定義されます。 いくつかのレガシーフォーマットの詳細は、HTMLへのメディアコンテナからのインバンドメディアリソーストラックの取得で確認できます。[INBAND]
メディアリソースが ユーザーエージェントが認識し、テキストトラック として同等とみなされるデータを含む場合、ユーザーエージェントはその関連データでメディアリソース固有のテキストトラックを公開する手順を実行します。
関連するデータを新しいテキストトラックおよび対応する新しい
TextTrackオブジェクトに関連付けます。
テキストトラックは、メディアリソース固有のテキストトラックです。
新しいテキストトラックの種別、ラベル、および言語を、関連データの意味に基づいて設定します。 そのデータにラベルがない場合は、ラベルを空文字列に設定しなければなりません。
テキストトラックのキューリストを そのフォーマットに適したテキストトラックレンダリングの更新ルールと関連付けます。
新しいテキストトラックの種別がchapters
またはmetadataである場合は、インバンドメタデータトラックのディスパッチタイプ
を次のように設定します。
CodecID要素の値に設定されなければなりません。[WEBMCG]
moovボックスの
trakボックス内の最初のmdiaボックスの
最初のminfボックスの
最初のstblボックスの
最初のstsdボックスをstsdボックスとします(存在する場合)。
ファイルにstsdボックスがない場合、またはstsdボックスにmettボックスもmetxボックスもない場合、インバンドメタデータトラックのディスパッチタイプは空の文字列に設定されなければなりません。
それ以外の場合、stsdボックスにmettボックスがある場合は、インバンドメタデータトラックのディスパッチタイプは、文字列"mett"、U+0020スペース文字、および最初のmettボックスの最初のmime_formatフィールドの値の連結したものに設定されなければなりません。
そのボックスにそのフィールドがない場合は、空の文字列に設定されなければなりません。
それ以外の場合、stsdボックスにmettボックスはなく、metxボックスがある場合は、インバンドメタデータトラックのディスパッチタイプ
は、文字列"metx"、U+0020スペース文字、および最初のmetxボックスの最初のnamespaceフィールドの値の連結したものに設定されなければなりません。
そのボックスにそのフィールドがない場合は、空の文字列に設定されなければなりません。
[MPEG4]
新しいテキストトラックのキューリストをこれまでに解析されたキューで埋め、キューの公開に関するガイドラインに従い、それを動的に更新し始めます。
新しいテキストトラックのモードを、ユーザーの好みや関連する仕様の要求に一致するモードに設定します。
例えば、他にアクティブな字幕がなく、これが強制字幕トラック(音声トラックの主要な言語で字幕を提供するが、実際に他の言語での音声にのみ字幕を提供する)である場合、ここでその字幕がアクティブになるかもしれません。
新しいテキストトラックをメディア要素のテキストトラックのリストに追加します。
イベントをaddtrack
という名前でメディア要素のtextTracks
属性のTextTrackList
オブジェクトに対して発生させ、TrackEventを使用して、
track属性をテキストトラックのTextTrackオブジェクトに初期化します。
track要素が作成されると、新しいテキストトラック(以下で定義される値が設定されたもの)および対応する新しい
TextTrackオブジェクトと関連付けられなければなりません。
テキストトラックの種別は、要素のkind属性の状態に基づき、次の表に従って決定されます。
最初の列に記載されている状態に対して、種別は2列目に示される文字列です。
| 状態 | 文字列 |
|---|---|
| 字幕 | subtitles
|
| キャプション | captions
|
| 説明 | descriptions
|
| チャプターメタデータ | chapters
|
| メタデータ | metadata
|
テキストトラックのラベルは、この要素のトラックラベルです。
テキストトラックの言語は、要素のトラックの言語(存在する場合)であり、存在しない場合は空文字列です。
kind、label、およびsrclang属性が設定、変更、または削除されると、テキストトラックは、上記の定義に従って更新されなければなりません。
トラックURLの変更は、以下のアルゴリズムで処理されます。
テキストトラックの準備状態は初期状態では未ロードであり、テキストトラックのモードは初期状態では無効です。
テキストトラックのキューリストは初期状態では空です。参照されたファイルが解析されると動的に変更されます。このリストに関連するのは、該当するフォーマットに適したテキストトラックのレンダリングを更新するためのルールであり、WebVTTの場合、これはWebVTTテキストトラックの表示を更新するためのルールです。[WEBVTT]
track要素の親要素が変更され、新しい親がメディア要素の場合、ユーザーエージェントはそのtrack要素に対応するテキストトラックをメディア要素のテキストトラックのリストに追加し、メディア要素タスクをキューに入れ、そのメディア要素に対してイベントをaddtrackという名前で発生させなければなりません。
これは、メディア要素のtextTracks属性のTextTrackListオブジェクトを使用して行われ、TrackEventを使用して、track属性がテキストトラックのTextTrackオブジェクトに初期化されます。
track要素の親要素が変更され、古い親がメディア要素であった場合、ユーザーエージェントはそのtrack要素に対応するテキストトラックをメディア要素のテキストトラックのリストから削除し、メディア要素タスクをキューに入れ、そのメディア要素に対してイベントをremovetrackという名前で発生させなければなりません。
これは、メディア要素のtextTracks属性のTextTrackListオブジェクトを使用して行われ、TrackEventを使用して、track属性がテキストトラックのTextTrackオブジェクトに初期化されます。
テキストトラックが、track要素に対応してメディア要素のテキストトラックのリストに追加されると、ユーザーエージェントは、そのメディア要素に対して次の手順を実行するためにメディア要素タスクをキューに入れなければなりません。
要素のparserによるブロックフラグがtrueの場合、戻ります。
要素の自動トラック選択を実行したフラグがtrueの場合、戻ります。
この要素に対して自動テキストトラック選択のユーザープリファレンスを尊重します。
ユーザーエージェントがメディア要素に対して自動テキストトラック選択のユーザープリファレンスを尊重する必要がある場合、次の手順を実行します。
自動テキストトラック選択を実行し、subtitlesおよびcaptionsを選択します。
自動テキストトラック選択を実行し、descriptionsを選択します。
メディア要素のテキストトラックのリストに、テキストトラックが含まれており、そのテキストトラックの種別がchaptersまたはmetadataに対応するtrack要素があり、そのdefault属性が設定され、テキストトラックのモードが無効に設定されている場合、これらすべてのトラックのテキストトラックのモードをに設定します。
要素の自動トラック選択を実行したフラグをtrueに設定します。
上記の手順でテキストトラックの種別に対して自動テキストトラック選択を実行すると言われた場合、それは次の手順を実行することを意味します。
アルゴリズムに渡された種別のいずれかに対応するテキストトラックで構成されたリストを、メディア要素のテキストトラックのリストから取得し、そのリストを候補とします。
候補が空の場合、戻ります。
候補の中に、テキストトラックのテキストトラックのモードが表示中に設定されているものがある場合、戻ります。
ユーザーが候補のトラックの中から、そのテキストトラックの種別、テキストトラックの言語、およびテキストトラックのラベルに基づいてトラックを有効にしたいという意向を示している場合、そのトラックのテキストトラックのモードを表示中に設定します。
例えば、ユーザーが「可能であればフランス語のキャプションを表示したい」、「タイトルに『コメント』が含まれている字幕トラックがあれば、それを有効にしたい」、「オーディオディスクリプショントラックが利用可能であれば、有効にする。できればスイスドイツ語で、無理なら標準スイスドイツ語か標準ドイツ語でもよい」というブラウザの設定を行っている可能性があります。
それ以外の場合、候補の中にテキストトラックがあり、それがtrack要素に対応し、default属性が設定され、テキストトラックのモードが無効に設定されている場合、その最初のトラックのテキストトラックのモードを表示中に設定します。
テキストトラックがtrack要素に対応しており、次のいずれかの状況に遭遇した場合、ユーザーエージェントはそのテキストトラックおよびtrack要素に対してtrack処理モデルを開始しなければなりません。
track要素が作成される。
track要素の親要素が変更され、新しい親がメディア要素である。
ユーザーエージェントがテキストトラックおよびtrack要素に対してtrack処理モデルを開始する場合、次のアルゴリズムを実行しなければなりません。このアルゴリズムは、イベントループメカニズムと密接に連携しており、特に同期セクションを持っています(これはイベントループアルゴリズムの一部としてトリガーされます)。そのセクション内の手順は⌛でマークされています。
このアルゴリズムの別の実行が、このテキストトラックおよびtrack要素に対してすでに進行中である場合、戻り、その他のアルゴリズムにこの要素の処理を任せます。
テキストトラックのテキストトラックのモードがまたは表示中のいずれかに設定されていない場合、戻ります。
これらの手順の残りの部分を並列で実行し、これらの手順を実行させた原因が引き続き進行できるようにします。
トップ: 安定状態を待ちます。同期セクションは以下の手順で構成されています。(同期セクションの手順は⌛でマークされています。)
⌛ テキストトラックの準備状態を読み込み中に設定します。
⌛ track要素の親がメディア要素である場合、corsAttributeStateをその親であるメディア要素のcrossoriginコンテンツ属性の状態とします。それ以外の場合は、corsAttributeStateをNo
CORSとします。
URLが空文字列でない場合、次の手順を実行します。
requestを、URL、"track"、およびcorsAttributeStateを用いて潜在的なCORSリクエストの作成の結果とし、同一オリジンのフォールバックフラグを設定します。
requestのクライアントを、track要素のノードドキュメントの関連する設定オブジェクトに設定します。
requestのイニシエータータイプを"track"に設定します。
requestをフェッチします。
フェッチングアルゴリズムによってネットワーキングタスクソースでキューに入れられたタスクは、データがフェッチされている間にリソースのタイプを判定する必要があります。リソースのタイプがサポートされているテキストトラック形式でない場合、ロードは失敗し、以下で説明されるように失敗します。そうでなければ、リソースのデータは、適切なパーサー(例:WebVTTパーサー)に受信時に渡され、その出力にテキストトラックのキューリストが使用されます。[WEBVTT]
適切なパーサーは、これらのネットワーキングタスクソースのタスクの実行中に、受信したデータを用いてテキストトラックのキューリストを段階的に更新します。
この仕様では、テキストトラックのMIMEタイプをチェックする方法や、それを行うかどうか、または実際のファイルデータを使用してファイルタイプのスニッフィングを行う方法やそれを行うかどうかについて、現在は記載されていません。この問題に関して実装者の意図が異なるため、適切な解決策が不明確です。この点に関する要件がない場合、HTTP仕様の厳格な要件であるContent-Typeヘッダーに従う必要があります("Content-Typeは基礎となるデータのメディアタイプを指定します。" ... "メディアタイプがContent-Typeフィールドによって与えられていない場合に限り、受信者はそのコンテンツおよび/またはリソースを識別するために使用されるURIの名前拡張子を検査してメディアタイプを推測することができます。")。
フェッチが何らかの理由で失敗した場合(ネットワークエラー、サーバーがエラーコードを返す、CORSが失敗するなど)、またはURLが空文字列である場合は、要素タスクをキューに入れ、DOM操作タスクソースを使用してメディア要素に対して最初にテキストトラックの準備状態をロードに失敗に変更し、次にエラーという名前のイベントを発生させます。
フェッチが失敗せず、リソースのタイプがサポートされているテキストトラック形式でないか、ファイルが正常に処理されなかった場合(例えば、その形式がXML形式であり、ファイルにXMLが要求する整形式エラーが含まれていて、アプリケーションに報告される必要がある場合)、上記の問題が見つかった場合にネットワーキングタスクソースでキューに入れられたタスクは、テキストトラックの準備状態をロードに失敗に変更し、エラーという名前のイベントを発生させます。
フェッチが失敗せず、ファイルが正常に処理された場合、データの解析が終了した後に、ネットワーキングタスクソースでキューに入れられた最終的なタスクは、テキストトラックの準備状態を読み込み済みに変更し、ロードという名前のイベントを発生させます。
フェッチが進行中に、次のいずれかの事象が発生した場合:
...その場合、ユーザーエージェントはフェッチを中止し、そのアルゴリズムによって生成された保留中のタスクを破棄しなければなりません(特に、URLが変更された後にキューを追加しないようにします)。その後、track要素に対してDOM操作タスクソースで要素タスクをキューに入れ、テキストトラックの準備状態をロードに失敗に変更し、エラーという名前のイベントを発生させます。
テキストトラックの準備状態が読み込み中でなくなるまで待ちます。
トラックURLがURLと一致しなくなるまで待ちます。その際にテキストトラックのモードがまたは表示中に設定されています。
トップに戻ります。
track要素のsrc属性が設定、変更、または削除されると、ユーザーエージェントはその要素のテキストトラックのテキストトラックのキューリストを直ちに空にしなければなりません。(これにより、以前に指定されたURLを使用して取得されたリソースからのキューの追加が停止されます。)
特定の形式のテキストトラックキューがHTMLユーザーエージェントによる処理のためにどのように解釈されるかは、その形式によって定義されます。そのような仕様がない場合、このセクションは、実装が一貫してそのような形式を公開しようとする際のいくつかの制約を提供します。
HTMLのテキストトラックモデルをサポートするために、タイムデータの各単位はテキストトラックキューに変換されます。この仕様で定義されているように、形式の機能をテキストトラックキューの側面にマッピングする方法が定義されていない場合、実装は、上記のテキストトラックキューの側面の定義に一致するマッピングであること、および以下の制約に一致することを確保しなければなりません:
形式に対する明確なアナログがない場合は、空の文字列に設定する必要があります。
偽に設定する必要があります。
すべての現行エンジンでサポートされています。
[Exposed =Window ]
interface TextTrackList : EventTarget {
readonly attribute unsigned long length ;
getter TextTrack (unsigned long index );
TextTrack ? getTrackById (DOMString id );
attribute EventHandler onchange ;
attribute EventHandler onaddtrack ;
attribute EventHandler onremovetrack ;
};
media.textTracks.length
すべての現行エンジンでサポートされています。
メディア要素(例:track要素)に関連付けられているテキストトラックの数を返します。
これは、メディア要素内のテキストトラックのリスト内のテキストトラックの数です。
media.textTracks[ n ]
textTrack = media.textTracks.getTrackById(id)
すべての現行エンジンでサポートされています。
指定された識別子を持つTextTrackオブジェクトを返しますが、その識別子を持つトラックがない場合は null を返します。
TextTrackListオブジェクトは、指定された順序でテキストトラックの動的に更新されるリストを表します。
メディア要素のtextTracks属性は、テキストトラックのリスト内のTextTrackオブジェクトを表すTextTrackListオブジェクトを返さなければなりません。同じ順序でなければなりません。
すべての現行エンジンでサポートされています。
TextTrackListオブジェクトのlength属性は、そのリスト内のテキストトラックの数を返さなければなりません。
サポートされているプロパティインデックスは、TextTrackListオブジェクト内のテキストトラックの数から1を引いた数です。リストにテキストトラックがない場合、サポートされているプロパティインデックスは存在しません。
インデックスプロパティの値を決定するには、TextTrackListオブジェクトで与えられたインデックスindexの値を決定し、TextTrackListオブジェクトで表されるリスト内のindex番目のテキストトラックを返さなければなりません。
TextTrackListオブジェクト内のTextTrackオブジェクトを最初にid属性の値と一致するトラックを見つけ、引数idに指定された値と一致する値を持つ最初のトラックを返さなければなりません。指定された引数に一致するトラックがない場合は、null
を返さなければなりません。
すべての現行エンジンでサポートされています。
enum TextTrackMode { " disabled " , " hidden " , " showing " };
enum TextTrackKind { " subtitles " , " captions " , " descriptions " , " chapters " , " metadata " };
[Exposed =Window ]
interface TextTrack : EventTarget {
readonly attribute TextTrackKind kind ;
readonly attribute DOMString label ;
readonly attribute DOMString language ;
readonly attribute DOMString id ;
readonly attribute DOMString inBandMetadataTrackDispatchType ;
attribute TextTrackMode mode ;
readonly attribute TextTrackCueList ? cues ;
readonly attribute TextTrackCueList ? activeCues ;
undefined addCue (TextTrackCue cue );
undefined removeCue (TextTrackCue cue );
attribute EventHandler oncuechange ;
};
textTrack = media.addTextTrack(kind [, label [, language ] ])
新しいTextTrackオブジェクトを作成し、返します。また、メディア要素のテキストトラックのリストにも追加されます。
textTrack.kind
すべての現行エンジンでサポートされています。
テキストトラックの種類文字列を返します。
textTrack.label
すべての現行エンジンでサポートされています。
テキストトラックのラベルが存在する場合はそのラベルを返し、そうでない場合は空の文字列を返します(オブジェクトがユーザーに公開される場合、他の属性からカスタムラベルを生成する必要があることを示します)。
textTrack.language
すべての現行エンジンでサポートされています。
テキストトラックの言語文字列を返します。
textTrack.id
すべての現行エンジンでサポートされています。
指定されたトラックのIDを返します。
インバンドトラックの場合、これはフォーマットがメディアフラグメント構文をサポートしている場合に、フラグメントで使用できるIDであり、getTrackById()メソッドでも使用できます。
textTrack.inBandMetadataTrackDispatchType
TextTrack/inBandMetadataTrackDispatchType
テキストトラックインバンドメタデータトラックディスパッチタイプ文字列を返します。
textTrack.mode [ = value ]
すべての現行エンジンでサポートされています。
次のリストから、文字列としてテキストトラックモードを返します。
disabled"
テキストトラック無効モード。
モード。
showing"
テキストトラック表示モード。
設定可能で、モードを変更するために使用されます。
textTrack.cues
すべての現行エンジンでサポートされています。
テキストトラックのすべてのキューのリストを、TextTrackCueListオブジェクトとして返します。
textTrack.activeCues
すべての現行エンジンでサポートされています。
現在アクティブなテキストトラックのキューを、TextTrackCueListオブジェクトとして返します。このキューは、現在の再生位置の前に開始し、その後に終了するものです。
textTrack.addCue(cue)
すべての現行エンジンでサポートされています。
指定されたキューをtextTrackのテキストトラックのキューのリストに追加します。
textTrack.removeCue(cue)
すべての現行エンジンでサポートされています。
指定されたキューをtextTrackのテキストトラックのキューのリストから削除します。
メディア要素のaddTextTrack(kind, label,
language)メソッドが呼び出されたとき、次の手順を実行する必要があります:
新しいTextTrackオブジェクトを作成します。
新しいオブジェクトに対応するテキストトラックを作成し、そのテキストトラックの種類をkindに、テキストトラックのラベルをlabelに、テキストトラックの言語をlanguageに設定し、テキストトラックの準備状態をテキストトラックの読み込み状態に、テキストトラックのモードをモードに設定し、テキストトラックのキューのリストを空のリストに設定します。
初めは、テキストトラックのキューのリストは、テキストトラックのレンダリングを更新するルールには関連付けられていません。テキストトラックのキューが追加されると、そのテキストトラックのキューのリストは、それに応じてルールが恒久的に設定されます。
新しいテキストトラックをメディア要素のテキストトラックのリストに追加します。
メディア要素タスクをキューに入れ、メディア要素でイベントを発火させ、メディア要素のtextTracks属性のTextTrackListオブジェクトに、新しいテキストトラックのTextTrackオブジェクトで初期化されたTrackEventを使用して、addtrackという名前のイベントを発生させます。
新しいTextTrackオブジェクトを返します。
kind
属性は、TextTrackオブジェクトが表すテキストトラックのテキストトラックの種類を返さなければなりません。
label
属性は、TextTrackオブジェクトが表すテキストトラックのテキストトラックのラベルを返さなければなりません。
language
属性は、TextTrackオブジェクトが表すテキストトラックのテキストトラックの言語を返さなければなりません。
id
属性は、トラックの識別子を返します。識別子がない場合は空の文字列を返します。track要素に対応するトラックの場合、トラックの識別子はその要素のid属性の値です。インバンドトラックの場合、トラックの識別子はメディアリソースによって指定されます。メディアリソースがメディアフラグメント構文をサポートしている形式である場合、特定のトラックに対して返される識別子は、そのフラグメントのトラック次元の名前として使用された場合にトラックを有効にするのと同じ識別子でなければなりません。
inBandMetadataTrackDispatchType
属性は、TextTrackオブジェクトが表すテキストトラックのテキストトラックのインバンドメタデータトラックディスパッチタイプを返さなければなりません。
mode
属性の取得時には、TextTrackオブジェクトが表すテキストトラックのテキストトラックモードに対応する文字列を、以下のリストで定義されているように返さなければなりません:
disabled"
hidden"
showing"
設定時、新しい値が現在の属性の返り値と等しくない場合、新しい値は次のように処理されなければなりません:
disabled"の場合
TextTrackオブジェクトが表すテキストトラックのテキストトラックモードをテキストトラック無効モードに設定します。
TextTrackオブジェクトが表すテキストトラックのテキストトラックモードをモードに設定します。
showing"の場合
TextTrackオブジェクトが表すテキストトラックのテキストトラックモードをテキストトラック表示モードに設定します。
TextTrackオブジェクトが表すテキストトラックのテキストトラックモードがテキストトラック無効モードでない場合、cues属性は、TextTrackCueListオブジェクトのライブであり、TextTrackオブジェクトが表すテキストトラックのテキストトラックのキューのリストのうち、終了時間がスクリプトが開始したときの最も早い可能な位置に発生するか、それ以降に発生する部分をテキストトラックのキュー順序に従って表すものでなければなりません。それ以外の場合はnullを返さなければなりません。各TextTrackオブジェクトに対して、オブジェクトが返される場合は、毎回同じTextTrackCueListオブジェクトを返さなければなりません。
スクリプトが開始したときの最も早い可能な位置は、前回イベントループがステップ1に到達したときの最も早い可能な位置です。
TextTrackオブジェクトが表すテキストトラックのテキストトラックモードがテキストトラック無効モードでない場合、activeCues属性は、TextTrackCueListオブジェクトのライブであり、TextTrackオブジェクトが表すテキストトラックのテキストトラックのキューのリストのうち、スクリプトが開始したときにアクティブフラグが設定されていた部分をテキストトラックのキュー順序に従って表すものでなければなりません。それ以外の場合はnullを返さなければなりません。各TextTrackオブジェクトに対して、オブジェクトが返される場合は、毎回同じTextTrackCueListオブジェクトを返さなければなりません。
テキストトラックのキューのスクリプトが開始したときにアクティブフラグが設定されていた場合、そのテキストトラックキューアクティブフラグは、前回イベントループがステップ1に到達したときに設定されていました。
addCue(cue) メソッドは、 TextTrack
オブジェクトに対して呼び出されたとき、次の手順を実行する必要があります:
テキストトラックのキューのリスト がまだ関連する テキストトラックレンダリングの更新ルール を持っていない場合は、 テキストトラックのキューのリスト を cue に適したテキストトラックレンダリングの更新ルール に関連付けます。
テキストトラックのキューのリスト
に関連付けられた テキストトラックレンダリングの更新ルール が、
cue に適した テキストトラックレンダリングの更新ルール
と同じでない場合は、 "InvalidStateError" を投げます。
指定された cue が テキストトラックのキューのリスト に含まれている場合、その テキストトラックのキューのリスト から cue を削除します。
cue を TextTrack オブジェクトの
テキストトラック の テキストトラックのキューのリスト
に追加します。
removeCue(cue) メソッドは、 TextTrack
オブジェクトに対して呼び出されたとき、次の手順を実行する必要があります:
指定された cue が TextTrack
オブジェクトの テキストトラック の テキストトラックのキューのリスト
に含まれていない場合、 "NotFoundError" を投げます。
cue を TextTrack オブジェクトの
テキストトラック の テキストトラックのキューのリスト
から削除します。
この例では、 audio
要素を使用して、複数のサウンドエフェクトを含む音声ファイルから特定のサウンドエフェクトを再生します。ブラウザがスクリプトを実行中でも、オーディオがクリップの終わりで正確に停止するように、キューを使用してオーディオを一時停止します。スクリプトに頼ってオーディオを一時停止していた場合、ブラウザが指定された時間にスクリプトを実行できなかった場合、次のクリップの開始が聞こえる可能性があります。
var sfx = new Audio( 'sfx.wav' );
var sounds = sfx. addTextTrack( 'metadata' ); >
// 追加するサウンドエフェクト
function addFX( start, end, name) {
var cue = new VTTCue( start, end, '' ); >
cue. id = name;
cue. pauseOnExit = true ;
sounds. addCue( cue); >
} >
addFX( 12.783 , 13.612 , 'dog bark' ); >
addFX( 13.612 , 15.091 , 'kitten mew' ); >
function playSound( id) {
sfx. currentTime = sounds. getCueById( id). startTime;
sfx. play(); >
} >
// 準備が整ったらすぐに鳴らす
sfx. oncanplaythrough = function () { >
playSound( 'dog bark' ); >
} >
// ユーザーがページを離れようとしたときにニャーと鳴き、ブラウザに確認を求める
window. onbeforeunload = function ( e) {
playSound( 'kitten mew' ); >
e. preventDefault(); >
}
すべての現在のエンジンでサポートされています。
[Exposed =Window ]
interface TextTrackCueList {
readonly attribute unsigned long length ;
getter TextTrackCue (unsigned long index );
TextTrackCue ? getCueById (DOMString id );
};
cuelist.length
リスト内の キュー の数を返します。
cuelist[index]
リスト内の index 番目の テキストトラックキュー を返します。キューは テキストトラックキューの順序 で並べられています。
cuelist.getCueById(id)
id に一致する最初の テキストトラックキュー を返します(テキストトラックキューの順序 で)。
指定された識別子を持つキューがない場合、または引数が空の文字列である場合、null を返します。
TextTrackCueList
オブジェクトは、指定された順序で テキストトラックキュー
の動的に更新されるリストを表します。
すべての現在のエンジンでサポートされています。
length 属性は、TextTrackCueList
オブジェクトによって表されるリスト内の キュー の数を返さなければなりません。
サポートされているプロパティのインデックス は、TextTrackCueList
オブジェクトによって表されるリスト内の キュー の数から 0
を引いた数までの範囲の数字です。リストにキューがない場合、サポートされているプロパティのインデックスはありません。
特定のインデックス index のプロパティ値を決定するには、ユーザーエージェントは TextTrackCueList
オブジェクトによって表されるリスト内の index 番目の テキストトラックキュー を返さなければなりません。
すべての現在のエンジンでサポートされています。
getCueById(id) メソッドは、空の文字列以外の引数で呼び出された場合、TextTrackCueList
オブジェクトによって表されるリスト内で、テキストトラックキュー の 識別子 が id
と一致する最初のキューを返さなければなりません。存在しない場合は null を返します。引数が空の文字列の場合、メソッドは null を返さなければなりません。
すべての現在のエンジンでサポートされています。
[Exposed =Window ]
interface TextTrackCue : EventTarget {
readonly attribute TextTrack ? track ;
attribute DOMString id ;
attribute double startTime ;
attribute unrestricted double endTime ;
attribute boolean pauseOnExit ;
attribute EventHandler onenter ;
attribute EventHandler onexit ;
};
cue.trackTextTrack オブジェクトにこの テキストトラックキュー が属している場合はそのオブジェクトを返し、それ以外の場合は null を返します。
cue.id [ = value ]
テキストトラックキュー識別子を返します。
設定することもできます。
cue.startTime [ = value ]
テキストトラックキューの開始時間を秒単位で返します。
設定することもできます。
cue.endTime [ = value ]
テキストトラックキューの終了時間を秒単位で返します。
無制限のテキストトラックキューの場合は、正の無限大を返します。
設定することもできます。
cue.pauseOnExit [ = value ]
テキストトラックキューの終了時に一時停止フラグが設定されている場合は true を返し、そうでない場合は false を返します。
設定することもできます。
すべての現在のエンジンでサポートされています。
track
属性は、取得時に、TextTrack オブジェクトが属する テキストトラック の キューのリスト に、テキストトラックキュー が含まれている場合、そのオブジェクトを返します。そうでない場合は null を返します。
すべての現在のエンジンでサポートされています。
id
属性は、取得時に、テキストトラックキュー識別子を返します。設定時には、新しい値に設定されます。
すべての現在のエンジンでサポートされています。
startTime 属性は、取得時に、テキストトラックキューの開始時間を秒単位で返します。設定時には、新しい値に設定され、秒単位で解釈されます。その後、TextTrackCue オブジェクトが テキストトラック の キューのリスト に含まれ、その テキストトラック が メディア要素 の テキストトラックのリスト に含まれ、かつその メディア要素 の ポスターフラグ が設定されていない場合は、その メディア要素 に対して 時間進行 ステップを実行します。
すべての現在のエンジンでサポートされています。
endTime 属性は、取得時に、テキストトラックキューの終了時間を秒単位で返します。設定時には、もし新しい値が負の無限大または
NaN(非数)であれば、TypeError
例外をスローします。それ以外の場合、新しい値に設定されます。その後、TextTrackCue オブジェクトが テキストトラック の キューのリスト に含まれ、その テキストトラック が メディア要素 の テキストトラックのリスト に含まれ、かつその メディア要素 の ポスターフラグ が設定されていない場合は、その メディア要素 に対して 時間進行 ステップを実行します。
すべての現在のエンジンでサポートされています。
pauseOnExit 属性は、取得時に、テキストトラックキューの終了時に一時停止フラグが設定されている場合は true
を返し、そうでない場合は false を返します。設定時には、新しい値が true の場合はフラグを設定し、それ以外の場合はフラグを解除します。
以下は、イベントハンドラーと、その対応するイベントハンドラーイベントタイプであり、すべてのTextTrackListインターフェイスを実装するオブジェクトが、イベントハンドラーIDL属性としてサポートしなければならないものです。
| イベントハンドラー | イベントハンドラーイベントタイプ |
|---|---|
onchange
| change
|
onaddtrack
| addtrack
|
onremovetrack
| removetrack
|
以下は、イベントハンドラーと、その対応するイベントハンドラーイベントタイプであり、すべてのTextTrackインターフェイスを実装するオブジェクトが、イベントハンドラーIDL属性としてサポートしなければならないものです。
| イベントハンドラー | イベントハンドラーイベントタイプ |
|---|---|
oncuechange
すべての現在のエンジンでサポートされています。 Firefox31+Safari6+Chrome23+
Opera12.1+Edge79+ Edge (Legacy)12+Internet Explorer10+ Firefox Android?Safari iOS7+Chrome Android?WebView Android?Samsung Internet?Opera Android12.1+ | cuechange
|
以下は、イベントハンドラーと、その対応するイベントハンドラーイベントタイプであり、すべてのTextTrackCueインターフェイスを実装するオブジェクトが、イベントハンドラーIDL属性としてサポートしなければならないものです。
| イベントハンドラー | イベントハンドラーイベントタイプ |
|---|---|
onenter
すべての現在のエンジンでサポートされています。 Firefox31+Safari6+Chrome23+
Opera12.1+Edge79+ Edge (Legacy)12+Internet Explorer10+ Firefox Android?Safari iOS7+Chrome Android?WebView Android?Samsung Internet?Opera Android12.1+ | enter
|
onexit
すべての現在のエンジンでサポートされています。 Firefox31+Safari6+Chrome23+
Opera12.1+Edge79+ Edge (Legacy)12+Internet Explorer10+ Firefox Android?Safari iOS7+Chrome Android?WebView Android?Samsung Internet?Opera Android12.1+ | exit
|
このセクションは規範的ではありません。
テキストトラックは、インタラクティブまたは拡張されたビューのために、メディアデータに関連するデータを保存するために使用できます。
例えば、スポーツ放送を表示するページには、現在のスコアに関する情報が含まれる可能性があります。たとえば、ロボットコンペティションがライブ配信されているとします。画像にスコアをオーバーレイすることができます。以下のように表示されます。
ユーザーがビデオの任意のポイントにシークする際に、スコア表示を正しくレンダリングするためには、メタデータテキストトラックのキューはスコアに適した長さである必要があります。例えば、上記のフレームでは、試合番号を示すキューが試合の長さに対応して存在し、青チームのスコアが変わるまで続くキューが1つ、赤チームのスコアが変わるまで続くキューが1つ存在する可能性があります。ビデオがライブイベントのストリームである場合、右下の時間は通常、キューに基づくのではなく、現在のビデオ時間から自動的に導出されると考えられます。しかし、ビデオがハイライトだけである場合、その時間もキューに含まれる可能性があります。
次に示すのは、WebVTTファイルの断片がどのように見えるかを示しています。
WEBVTT ... 05:10:00.000 --> 05:12:15.000 matchtype:qual matchnumber:37 ... 05:11:02.251 --> 05:11:17.198 red:78 05:11:03.672 --> 05:11:54.198 blue:66 05:11:17.198 --> 05:11:25.912 red:80 05:11:25.912 --> 05:11:26.522 red:83 05:11:26.522 --> 05:11:26.982 red:86 05:11:26.982 --> 05:11:27.499 red:89 ...
ここでのポイントは、情報が関連するイベントに適用される時間の長さにまたがるキューで提供されていることに注意することです。代わりに、スコアがゼロ長(またはほぼゼロ長)のキューとして提供される場合、例えば05:11:17.198の「red+2」、05:11:25.912の「red+3」など、問題が発生します。主に、シークの実装が非常に難しくなり、スクリプトはすべてのキューのリストを調べて、通知が見逃されていないか確認する必要があります。また、キューが短い場合、スクリプトがそれらがアクティブであることを認識できない可能性があり、それを特別に監視しない限り、見逃す可能性があります。
このような方法でキューを使用する場合、著者は現在の注釈を更新するために、cuechangeイベントを使用することを推奨します。(特に、timeupdateイベントを使用するのはあまり適切ではありません。なぜなら、キューが変更されていない場合でも作業を行う必要があり、さらに重要なことに、メタデータキューがアクティブになる時点と表示が更新される時点の間に、高い遅延が発生するためです。timeupdateイベントはレート制限されています。)
URLを使用して、AudioTrackのkind
IDL属性や、VideoTrackのkind
IDL属性の戻り値、またはテキストトラックの種類を識別する必要がある他の仕様や形式は、about:html-kind
URLを使用しなければなりません。
controls属性は、ブール属性です。指定されている場合、作成者がスクリプト化されたコントローラーを提供しておらず、ユーザーエージェントに独自のコントロールセットを提供してほしいことを示します。
この属性が指定されている場合、またはスクリプトが無効化されている場合、メディア要素に対して、ユーザーエージェントはユーザーにユーザーインターフェースを提供する必要があります。このユーザーインターフェースには、再生の開始、再生の一時停止、コンテンツの任意の位置へのシーク(コンテンツが任意のシークをサポートしている場合)、音量の変更、クローズドキャプションや埋め込まれた手話トラックの表示の変更、異なるオーディオトラックの選択または音声説明のオンにすること、ユーザーに適した方法でのメディアコンテンツの表示(例:全画面ビデオや独立したリサイズ可能なウィンドウ)などの機能が含まれているべきです。他のコントロールも提供される場合があります。
ただし、この属性が指定されていない場合でも、ユーザーエージェントはメディアリソースの再生に影響を与えるコントロール(例:再生、一時停止、シーク、トラック選択、音量コントロール)を提供することができますが、そのような機能はページの通常のレンダリングを妨げるべきではありません。たとえば、そのような機能は、メディア要素のコンテキストメニュー、プラットフォームメディアキー、またはリモートコントロールで公開される可能性があります。ユーザーエージェントは、上記で説明したように、ユーザーにユーザーインターフェースを提供することによってこれを単純に実装することができます(まるでcontrols属性が指定されているかのように)。
ユーザーエージェントがユーザーにユーザーインターフェースを提供することにより、メディア要素上にコントロールを表示する場合、ユーザーエージェントがこのインターフェースと対話している間は、ユーザー操作イベントを抑制するべきです。(たとえば、ユーザーがビデオの再生コントロールをクリックした場合、mousedownイベントなどがページ上の要素に同時に発火されることはありません。)
可能であれば(具体的には、再生の開始、停止、一時停止、および再開、シーク、再生速度の変更、早送りまたは巻き戻し、テキストトラックのリスト化、有効化、無効化、およびオーディオのミュートや音量変更のために)、ユーザーエージェントによって公開されるユーザーインターフェース機能は、上記で説明したDOM APIの観点で実装されなければならないため、同じイベントがすべて発火します。
早送りや巻き戻しなどの機能は、playbackRate属性のみを変更することによって実装されなければなりません(defaultPlaybackRate属性は変更されません)。
シークは、シークして、メディア要素のメディアタイムラインの要求された位置に到達する観点で実装されなければなりません。任意の位置へのシークが遅くなるメディアリソースの場合、ユーザーがシークバーなどの近似位置インターフェースを操作したときに、ユーザーエージェントが速度優先の近似フラグを使用することが推奨されます。
すべての現在のエンジンでサポートされています。
controls
IDL属性は、同名のコンテンツ属性を反映しなければなりません。
media.volume [ = value ]
すべての現在のエンジンでサポートされています。
現在の再生音量を、0.0から1.0の範囲の数値として返します。0.0が最も静かで、1.0が最も大きい音量です。
音量を変更するために設定することができます。
新しい値が0.0から1.0の範囲にない場合、"IndexSizeError" DOMExceptionがスローされます。
media.muted [ = value ]
すべての現在のエンジンでサポートされています。
オーディオがミュートされている場合はtrueを返し、volume属性を無効にし、ミュートされていない場合はvolume属性が有効であることを示します。
オーディオがミュートされているかどうかを変更するために設定できます。
メディア要素には、0.0(無音)から1.0(最大音量)の範囲の分数である再生音量があります。初期状態では、音量は1.0であるべきですが、ユーザーエージェントはセッション間やサイトごとに、またはその他の方法で最後に設定された値を記憶している場合があるため、音量は他の値から開始する場合があります。
volume
IDL属性は、再生音量をメディア要素のオーディオ部分に返さなければなりません。設定時に、新しい値が0.0から1.0の範囲内にある場合、メディア要素の再生音量は新しい値に設定されなければなりません。新しい値が0.0から1.0の範囲外にある場合、設定時に"IndexSizeError" DOMExceptionがスローされなければなりません。
メディア要素は、ミュートにすることもできます。何かが要素をミュートしている場合、その要素はミュートされています。(たとえば、再生方向が逆の場合、その要素はミュートされています。)
muted
IDL属性は、最後に設定された値を返さなければなりません。メディア要素が作成されたとき、要素にmutedコンテンツ属性が指定されている場合は、muted
IDL属性はtrueに設定されるべきです。そうでない場合、ユーザーエージェントはユーザーの好みの値に設定することがあります(例:セッション間やサイトごとに、またはその他の方法で最後に設定された値を記憶している場合など)。muted IDL属性がtrueに設定されている間、メディア要素はミュートされなければなりません。
volumeおよびmutedIDL属性によって返される値が変更された場合、ユーザーエージェントはメディア要素タスクをキューに追加し、メディア要素でvolumechangeという名前のイベントを発火しなければなりません。その後、メディア要素が再生を許可されていない場合、ユーザーエージェントは内部一時停止手順を実行しなければなりません。
ユーザーエージェントには、音量ロック(ブール値)があります。その値は実装依存であり、再生音量が反映されるかどうかを決定します。
要素の効果的なメディア音量は、次のように決定されます。
ユーザーがユーザーエージェントに要素の音量を上書きするよう指示している場合、その音量を返します。
ユーザーエージェントの音量ロックがtrueである場合、システムの音量を返します。
要素のオーディオ出力がミュートされている場合、0を返します。
volumeを、再生音量とし、0.0(無音)から1.0(最大音量)の範囲で返します。
volumeを返し、0.0から1.0の範囲内で解釈し、0.0が無音で、1.0が最も大きい設定で、間の値が大きさを増します。この範囲は線形である必要はありません。最大設定は、システムの最大可能設定よりも低くてもよいです。たとえば、ユーザーが最大音量を設定した場合などです。
メディア要素上のmutedコンテンツ属性は、ブール属性であり、ユーザーの好みを無視して、メディアリソースのオーディオ出力のデフォルト状態を制御します。
すべての現在のエンジンでサポートされています。
defaultMuted IDL属性は、mutedコンテンツ属性を反映しなければなりません。
この属性には動的な効果はありません(要素のデフォルト状態を制御するだけです)。
このビデオ(広告)は自動再生されますが、ユーザーを煩わせないために、音声なしで再生され、ユーザーが音声をオンにすることができます。ユーザーエージェントは、ユーザー操作なしにビデオがミュート解除されると、一時停止することができます。
< video src = "adverts.cgi?kind=video" controls autoplay loop muted ></ video >
すべての現在のエンジンでサポートされています。
TimeRangesインターフェースを実装するオブジェクトは、時間の範囲(期間)のリストを表します。
[Exposed =Window ]
interface TimeRanges {
readonly attribute unsigned long length ;
double start (unsigned long index );
double end (unsigned long index );
};
media.length
すべての現在のエンジンでサポートされています。
オブジェクト内の範囲の数を返します。
time = media.start(index)
すべての現在のエンジンでサポートされています。
指定されたインデックスを持つ範囲の開始時刻を返します。
インデックスが範囲外の場合、"IndexSizeError" DOMExceptionをスローします。
time = media.end(index)
すべての現在のエンジンでサポートされています。
指定されたインデックスを持つ範囲の終了時刻を返します。
インデックスが範囲外の場合、"IndexSizeError" DOMExceptionをスローします。
length
IDL属性は、オブジェクトが表す範囲の数を返さなければなりません。
start(index)メソッドは、オブジェクトが表すindex番目の範囲の開始位置を、オブジェクトがカバーするタイムラインの開始から測定した秒数で返さなければなりません。
end(index)メソッドは、オブジェクトが表すindex番目の範囲の終了位置を、オブジェクトがカバーするタイムラインの開始から測定した秒数で返さなければなりません。
これらのメソッドは、オブジェクトが表す範囲の数以上のindex引数を指定して呼び出された場合、"IndexSizeError" DOMExceptionをスローしなければなりません。
TimeRangesオブジェクトが正規化されたTimeRangesオブジェクトとされる場合、それが表す範囲は次の基準を満たしていなければなりません。
言い換えれば、そのようなオブジェクトの範囲は順序付けられており、重複せず、接触していません(隣接する範囲は1つの大きな範囲に統合されます)。範囲は空であってもよい(時間の単一の瞬間を参照している)、たとえば、メディア要素が一時停止しているときに、ユーザーエージェントが現在のフレームを除くすべてのメディアリソースを破棄した場合などです。
TimeRangesオブジェクト内の範囲は、包含的でなければなりません。
したがって、範囲の終了は、次の隣接する(接触しているが重なっていない)範囲の開始と等しくなります。同様に、ゼロを基準にアンカーされたタイムライン全体をカバーする範囲は、開始がゼロで、終了がタイムラインの長さと等しくなります。
メディア要素のbuffered、seekable、およびplayedIDL属性によって返されるオブジェクトによって使用されるタイムラインは、その要素のメディアタイムラインでなければなりません。
TrackEventインターフェースすべての現在のエンジンでサポートされています。
[Exposed =Window ]
interface TrackEvent : Event {
constructor (DOMString type , optional TrackEventInit eventInitDict = {});
readonly attribute (VideoTrack or AudioTrack or TextTrack )? track ;
};
dictionary TrackEventInit : EventInit {
(VideoTrack or AudioTrack or TextTrack )? track = null ;
};
event.track
すべての現在のエンジンでサポートされています。
イベントが関連するトラックオブジェクト(TextTrack、AudioTrack、またはVideoTrack)を返します。
track属性は、初期化された値を返さなければなりません。これは、イベントのコンテキスト情報を表します。
このセクションは規範的ではありません。
以下のイベントは、上記の処理モデルの一部としてメディア要素で発生します。
| イベント名 | インターフェース | 発生条件 | 前提条件 |
|---|---|---|---|
loadstart
HTMLMediaElement/loadstart_event すべての現在のエンジンでサポートされています。 Firefox6+Safari4+Chrome3+
Opera12.1+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android?Samsung Internet?Opera Android12.1+ | Event
| ユーザーエージェントがメディアデータを探し始めたとき、リソース選択アルゴリズムの一部として発生します。 | networkStateがNETWORK_LOADINGと等しいとき。
|
progress
HTMLMediaElement/progress_event すべての現在のエンジンでサポートされています。 Firefox6+Safari3.1+Chrome3+
Opera12.1+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android?Samsung Internet?Opera Android12.1+ | Event
| ユーザーエージェントがメディアデータを取得しているとき。 | networkStateがNETWORK_LOADINGと等しいとき。
|
suspend
HTMLMediaElement/suspend_event すべての現在のエンジンでサポートされています。 Firefox3.5+Safari3.1+Chrome3+
Opera10.5+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android11+ | Event
| ユーザーエージェントが意図的に現在メディアデータを取得していないとき。 | networkStateがNETWORK_IDLEと等しいとき。
|
abort
すべての現在のエンジンでサポートされています。 Firefox9+Safari3.1+Chrome3+
Opera12.1+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android?Samsung Internet?Opera Android12.1+ | Event
| ユーザーエージェントがメディアデータを完全にダウンロードする前に取得を停止したが、それがエラーによるものではないとき。 | errorがMEDIA_ERR_ABORTEDコードを持つオブジェクトであるとき。networkStateがNETWORK_EMPTYまたはNETWORK_IDLEと等しい。
|
error
すべての現在のエンジンでサポートされています。 Firefox6+Safari3.1+Chrome3+
Opera11.6+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android?Samsung Internet?Opera Android12+ | Event
| エラーが発生し、メディアデータが取得できなかったか、リソースのタイプがサポートされていないメディア形式であるとき。 | errorがMEDIA_ERR_NETWORKまたはそれ以上のコードを持つオブジェクトであるとき。networkStateがNETWORK_EMPTYまたはNETWORK_IDLEと等しい。
|
emptied
HTMLMediaElement/emptied_event すべての現在のエンジンでサポートされています。 Firefox3.5+Safari3.1+Chrome3+
Opera10.5+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android11+ | Event
| 以前のnetworkStateがNETWORK_EMPTY状態ではなかったメディア要素が、その状態に切り替わったとき(致命的なエラーが発生し、報告される直前や、リソース選択アルゴリズムがすでに実行中のときにload()メソッドが呼び出された場合など)。
| networkStateがNETWORK_EMPTYであり、すべてのIDL属性が初期状態にある。
|
stalled
HTMLMediaElement/stalled_event すべての現在のエンジンでサポートされています。 Firefox3.5+Safari3.1+Chrome3+
Opera10.5+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android11+ | Event
| ユーザーエージェントがメディアデータを取得しようとしているが、データが予期せず届かない場合に発生します。 | networkStateがNETWORK_LOADINGと等しい。
|
loadedmetadata
HTMLMediaElement/loadedmetadata_event すべての現在のエンジンでサポートされています。 Firefox3.5+Safari3.1+Chrome3+
Opera10.5+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android11+ | Event
| ユーザーエージェントがメディアリソースの期間と寸法を判定し、テキストトラックが準備完了になったときに発生します。 | readyStateが初めてHAVE_METADATA以上になったとき。
|
loadeddata
HTMLMediaElement/loadeddata_event すべての現在のエンジンでサポートされています。 Firefox3.5+Safari3.1+Chrome3+
Opera10.5+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android11+ | Event
| ユーザーエージェントがメディアデータを現在の再生位置で初めてレンダリングできるようになったときに発生します。 | readyStateが初めてHAVE_CURRENT_DATA以上に増加したとき。
|
canplay
HTMLMediaElement/canplay_event すべての現在のエンジンでサポートされています。 Firefox3.5+Safari3.1+Chrome3+
Opera10.5+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android11+ | Event
| ユーザーエージェントがメディアデータを再生できるが、現在の再生レートでメディアリソースを終了まで再生するには、さらにバッファリングが必要だと推定されるときに発生します。 | readyStateが初めてHAVE_FUTURE_DATA以上に増加したとき。
|
canplaythrough
HTMLMediaElement/canplaythrough_event すべての現在のエンジンでサポートされています。 Firefox3.5+Safari3.1+Chrome3+
Opera10.5+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android11+ | Event
| ユーザーエージェントが、現在の再生レートでメディアリソースを終了までバッファリングせずに再生できると推定されたときに発生します。 | readyStateがHAVE_ENOUGH_DATAと等しい。
|
playing
HTMLMediaElement/playing_event すべての現在のエンジンでサポートされています。 Firefox3.5+Safari3.1+Chrome3+
Opera10.5+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android11+ | Event
| メディアデータの不足により一時停止または遅延した後に再生が準備できたときに発生します。 | readyStateがHAVE_FUTURE_DATA以上になったとき、pausedがfalseであるか、pausedがfalseに変更され、readyStateがHAVE_FUTURE_DATA以上に増加したとき。たとえこのイベントが発生しても、潜在的な再生が開始されない可能性があります。例えば、ユーザー操作のために一時停止されている場合や、インバンドコンテンツのために一時停止されている場合です。
|
waiting
HTMLMediaElement/waiting_event すべての現在のエンジンでサポートされています。 Firefox6+Safari3.1+Chrome3+
Opera12.1+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android12.1+ | Event
| 次のフレームが利用できないために再生が停止したが、ユーザーエージェントはそのフレームがすぐに利用可能になると予測しているとき。 | readyStateがHAVE_CURRENT_DATA以下であり、pausedがfalseである。seekingがtrueであるか、現在の再生位置がbufferedのいずれの範囲にも含まれていない。その他の理由で再生が停止することがあるが、pausedがfalseであってもこのイベントは発生しません(これらの状況が解決しても、別のplayingイベントが発生することはありません)。例えば、再生が終了した場合や、エラーのために再生が停止した場合、ユーザー操作のために一時停止された場合やインバンドコンテンツのために一時停止された場合です。
|
seeking
HTMLMediaElement/seeking_event すべての現在のエンジンでサポートされています。 Firefox3.5+Safari3.1+Chrome3+
Opera10.5+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android11+ | Event
| seeking IDL 属性が true
に変更され、ユーザーエージェントが新しい位置のシークを開始したときに発生します。
| |
seeked
すべての現在のエンジンでサポートされています。 Firefox3.5+Safari3.1+Chrome3+
Opera10.5+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android11+ | Event
| seeking IDL 属性が false
に変更され、現在の再生位置
が変更された後に発生します。
| |
ended
すべての現在のエンジンでサポートされています。 Firefox3.5+Safari3.1+Chrome3+
Opera10.5+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android11+ | Event
| メディアリソースの終わりに到達したために再生が停止した場合に発生します。 | currentTime が
メディアリソース の終わりと等しくなり、ended が true になります。
|
durationchange
HTMLMediaElement/durationchange_event すべての現在のエンジンでサポートされています。 Firefox3.5+Safari3.1+Chrome3+
Opera10.5+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android11+ | Event
| duration
属性が更新されたときに発生します。
| |
timeupdate
HTMLMediaElement/timeupdate_event すべての現在のエンジンでサポートされています。 Firefox3.5+Safari3.1+Chrome3+
Opera10.5+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android11+ | Event
| 現在の再生位置が、通常の再生の一環として、または特に興味深い方法で変更されたときに発生します。たとえば、不連続に変更された場合などです。 | |
play
すべての現在のエンジンでサポートされています。 Firefox3.5+Safari3.1+Chrome3+
Opera10.5+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android11+ | Event
| 要素が一時停止されなくなったときに発生します。 play() メソッドが戻った後、または autoplay
属性が再生を開始したときに発生します。
| paused が新たに false
になりました。
|
pause
すべての現在のエンジンでサポートされています。 Firefox3.5+Safari3.1+Chrome3+
Opera10.5+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android11+ | Event
| 要素が一時停止されたときに発生します。 pause()
メソッドが戻った後に発生します。
| paused が新たに true
になりました。
|
ratechange
HTMLMediaElement/ratechange_event すべての現在のエンジンでサポートされています。 Firefox3.5+Safari3.1+Chrome3+
Opera10.5+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android11+ | Event
| defaultPlaybackRate
または playbackRate
属性が更新されたときに発生します。
| |
resize
| Event
| いずれか、または両方の videoWidth および
videoHeight
属性が更新されたときに発生します。
| メディア要素 が ビデオ 要素であり、readyState が
HAVE_NOTHING
でない場合。
|
volumechange
HTMLMediaElement/volumechange_event すべての現在のエンジンでサポートされています。 Firefox6+Safari3.1+Chrome3+
Opera12.1+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android12.1+ | Event
| volume 属性または muted
属性が変更されたときに発生します。該当する属性のセッターが戻った後に発生します。
|
次のイベントは、source要素に対して発生します:
| イベント名 | インターフェース | 発生条件 |
|---|---|---|
error |
Event
|
メディアデータの取得中にエラーが発生するか、リソースのタイプがサポートされていないメディアフォーマットである場合。 |
以下のイベントは、AudioTrackList、VideoTrackList、およびTextTrackListオブジェクトで発生します:
| イベント名 | インターフェース | 発生するタイミング... |
|---|---|---|
change
すべての現行エンジンでサポートされています。 Firefox🔰 33+Safari7+Chrome🔰
37+
Opera?Edge🔰 79+ Edge (Legacy)いいえInternet Explorer10+ Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android? すべての現行エンジンでサポートされています。 Firefox31+Safari7+Chrome33+
Opera?Edge79+ Edge (Legacy)18Internet Explorerいいえ Firefox Android?Safari iOS?Chrome Android?WebView Android4.4+Samsung Internet?Opera Android? すべての現行エンジンでサポートされています。 Firefox🔰 33+Safari7+Chrome🔰
37+
Opera?Edge🔰 79+ Edge (Legacy)いいえInternet Explorer10+ Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android? |
Event
|
トラックリスト内の 1 つ以上のトラックが有効または無効になったとき。 |
addtrack
すべての現行エンジンでサポートされています。 Firefox🔰 33+Safari7+Chrome🔰
37+
Opera?Edge🔰 79+ Edge (Legacy)いいえInternet Explorer10+ Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android? すべての現行エンジンでサポートされています。 Firefox31+Safari6+Chrome23+
Opera12.1+Edge79+ Edge (Legacy)12+Internet Explorer11 Firefox Android?Safari iOS7+Chrome Android?WebView Android?Samsung Internet?Opera Android12.1+ すべての現行エンジンでサポートされています。 Firefox🔰 33+Safari7+Chrome🔰
37+
Opera?Edge🔰 79+ Edge (Legacy)いいえInternet Explorer10+ Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android? |
TrackEvent |
トラックリストにトラックが追加されたとき。 |
removetrack
AudioTrackList/removetrack_event すべての現行エンジンでサポートされています。 Firefox🔰 33+Safari7+Chrome🔰
37+
Opera?Edge🔰 79+ Edge (Legacy)いいえInternet Explorer10+ Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android? TextTrackList/removetrack_event すべての現行エンジンでサポートされています。 Firefox31+Safari7+Chrome33+
Opera20+Edge79+ Edge (Legacy)18Internet Explorerいいえ Firefox Android?Safari iOS?Chrome Android?WebView Android4.4+Samsung Internet?Opera Android20+ VideoTrackList/removetrack_event すべての現行エンジンでサポートされています。 Firefox🔰 33+Safari7+Chrome🔰
37+
Opera?Edge🔰 79+ Edge (Legacy)いいえInternet Explorer10+ Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android? |
TrackEvent |
トラックリストからトラックが削除されたとき。 |
以下のイベントは、TextTrackオブジェクトおよびtrack要素で発生します:
| イベント名 | インターフェース | 発生するタイミング... |
|---|---|---|
cuechange
HTMLTrackElement/cuechange_event すべての現行エンジンでサポートされています。 Firefox68+Safari10+Chrome32+
Opera19+Edge79+ Edge (Legacy)14+Internet Explorerいいえ Firefox Android?Safari iOS?Chrome Android?WebView Android4.4.3+Samsung Internet?Opera Android19+ すべての現行エンジンでサポートされています。 Firefox31+Safari6+Chrome23+
Opera12.1+Edge79+ Edge (Legacy)12+Internet Explorer10+ Firefox Android?Safari iOS7+Chrome Android?WebView Android?Samsung Internet?Opera Android12.1+ |
Event
|
トラック内の 1 つ以上のキューがアクティブになったか、アクティブでなくなったとき。 |
以下のイベントは、track要素で発生します:
| イベント名 | インターフェース | 発生するタイミング... |
|---|---|---|
error
|
Event
|
トラックデータの取得中にエラーが発生した場合、またはリソースのタイプがサポートされていないテキストトラック形式である場合。 |
load
|
Event
|
トラックデータが取得され、正常に処理された場合。 |
以下のイベントは、TextTrackCueオブジェクトで発生します:
| イベント名 | インターフェース | 発生するタイミング... |
|---|---|---|
enter
すべての現行エンジンでサポートされています。 Firefox31+Safari6+Chrome23+
Opera12.1+Edge79+ Edge (Legacy)12+Internet Explorer10+ Firefox Android?Safari iOS7+Chrome Android?WebView Android?Samsung Internet?Opera Android12.1+ |
Event
|
キューがアクティブになったとき。 |
exit
すべての現行エンジンでサポートされています。 Firefox31+Safari6+Chrome23+
Opera12.1+Edge79+ Edge (Legacy)12+Internet Explorer10+ Firefox Android?Safari iOS7+Chrome Android?WebView Android?Samsung Internet?Opera Android12.1+ |
Event
|
キューがアクティブでなくなったとき。 |
videoおよびaudio要素の主なセキュリティとプライバシーへの影響は、クロスオリジンでメディアを埋め込む機能に由来します。脅威が流れる方向は、悪意のあるコンテンツから被害者のページへのものと、悪意のあるページから被害者のコンテンツへのものの二方向です。
被害者のページが悪意のあるコンテンツを埋め込む場合、脅威はそのコンテンツに埋め込まれたスクリプトがDocumentに対して何らかの操作を試みる可能性があるということです。これを回避するために、ユーザーエージェントはコンテンツから埋め込んだページへのアクセスがないことを保証しなければなりません。DOMの概念を使用するメディアコンテンツの場合、埋め込まれたコンテンツは、独自の無関係なトップレベルのトラバース可能として扱わなければなりません。
例えば、SVGアニメーションがvideo要素に埋め込まれた場合、ユーザーエージェントは外側のページのDOMにアクセスさせません。SVGリソース内のスクリプトの視点から見ると、SVGファイルは親を持たない単独のトップレベルトラバース可能として表示されます。
悪意のあるページが被害者のコンテンツを埋め込む場合、脅威は埋め込みページがそれ以外ではアクセスできない情報をコンテンツから取得できることです。APIは、メディアの存在、その種類、継続時間、サイズ、およびホストのパフォーマンス特性などの情報を公開します。このような情報はすでに問題を引き起こす可能性がありますが、実際には同様の情報はimg要素を使用してもほぼ同様に取得できるため、許容されると考えられています。
しかし、ユーザーエージェントがコンテンツ内のメタデータ(字幕など)をさらに公開すると、はるかに機密性の高い情報が取得される可能性があります。そのため、この情報はビデオリソースがCORSを使用している場合にのみ公開されます。crossorigin属性は、CORSを有効にするために著者が使用できます。[FETCH]
この制限がなければ、攻撃者は企業ネットワーク内で実行中のユーザーをだまして、企業のイントラネット上の以前に漏洩した場所からビデオを読み込もうとするサイトにアクセスさせる可能性があります。そのようなビデオに新製品の機密計画が含まれていた場合、字幕を読むことができると深刻な機密情報の漏洩につながります。
このセクションは規範的ではありません。
セットトップボックスや携帯電話などの小型デバイスでオーディオおよびビデオリソースを再生する場合、デバイスのハードウェアリソースが限られていることが多いです。例えば、デバイスが同時にサポートできるビデオは3つだけかもしれません。このため、メディア要素が再生を終えたら、そのリソースを解放することが良いプラクティスです。これには、要素へのすべての参照を非常に慎重に削除し、ガベージコレクションが行われるようにするか、さらに良い方法として、要素のsrc属性を空の文字列に設定することが含まれます。srcObjectが設定されていた場合は、代わりにsrcObjectをnullに設定します。
同様に、再生速度が正確に1.0でない場合、ハードウェア、ソフトウェア、またはフォーマットの制限により、ビデオフレームがドロップしたり、音声が途切れたりミュートされたりする可能性があります。
このセクションは規範的ではありません。
さまざまな側面でメディア要素APIがどれだけ正確に実装されているかは、実装の品質に関する問題と見なされます。
例えば、buffered属性を実装する際、バッファされた範囲をどれだけ正確に報告するかは、ユーザーエージェントがデータをどれだけ慎重に検査するかに依存します。APIは範囲を時間として報告しますが、データはバイトストリームで取得されるため、可変ビットレートストリームを受信するユーザーエージェントは、すべてのデータを実際にデコードすることでのみ正確な時間を決定できるかもしれません。ただし、ユーザーエージェントがこれを行う必要はなく、代わりに推定値を返すことができます(たとえば、これまでに見られた平均ビットレートに基づいて)、その後の情報が利用可能になると修正されます。
一般的なルールとして、ユーザーエージェントは楽観的ではなく慎重であることが推奨されます。例えば、すべてがバッファされたと報告したが実際にはそうでなかった場合、それは問題です。
もう一つの実装の品質に関する問題は、コーデックが前方向の再生専用に設計されている場合にビデオを逆方向に再生することです(たとえば、キーフレームが少なく、それらが離れており、間のフレームは前のフレームからのデルタしか持たない場合)。ユーザーエージェントは、キーフレームのみを表示するなど、低品質な処理を行うかもしれません。しかし、より良い実装では、前方にビデオの部分を実際にデコードし、完全なフレームを保存し、それを逆方向に再生するなど、より多くの作業を行い、結果としてより良い処理を行います。
同様に、実装はいつでもバッファされたデータを破棄することが許可されていますが(メディア要素のライフタイム中に取得されたすべてのメディアデータをユーザーエージェントが保持する必要はありません)、これも実装の品質に関する問題です。十分なリソースを持つユーザーエージェントは、すべてのデータを保持することが推奨されます。これにより、より良いユーザー体験が可能になります。例えば、ユーザーがライブストリームを視聴している場合、ユーザーエージェントはユーザーにライブビデオのみを表示させることができますが、より優れたユーザーエージェントはすべてをバッファし、ユーザーが以前の素材をシークしたり、一時停止したり、前後に再生したりできるようにします。
メディア要素が一時停止中にドキュメントから削除され、イベントループがステップ1に到達する前に再挿入されない場合、リソースに制約のある実装は、その機会を利用して、メディア要素が使用するすべてのハードウェアリソース(ビデオプレーン、ネットワークリソース、データバッファなど)を解放することが推奨されます。(ただし、後で再生が再開された場合に備えて、ユーザーエージェントは再生位置などを追跡し続ける必要があります。)
map 要素全てのエンジンでサポートされています。
全てのエンジンでサポートされています。
name — イメージマップの名前を指定し、usemap属性から参照されるようにする
[Exposed =Window ]
インターフェイス HTMLMapElement : HTMLElement {
[HTMLConstructor ] コンストラクター ();
[CEReactions ] 属性 DOMString name ;
[SameObject ] readonly 属性 HTMLCollection areas ;
};
map要素は、img要素および任意のarea要素の子孫と組み合わせて、イメージマップを定義します。この要素はその子孫を表現します。
name属性は、マップに名前を与えて、参照できるようにします。この属性は必須であり、非空の値を持ち、ASCII空白文字を含まない必要があります。name属性の値は、同じツリー内の別のmap要素のname属性の値と一致してはなりません。id属性も指定されている場合、両方の属性は同じ値を持つ必要があります。
map.areas
HTMLCollectionを返します。area要素のmap。
areas属性は、HTMLCollectionを返さなければなりません。map要素をルートとし、フィルターがarea要素にのみ一致します。
ID属性nameは、同じ名前のコンテンツ属性を反映しなければなりません。
イメージマップは、ページ上の他のコンテンツと組み合わせて定義することができ、保守が容易です。この例は、ページの上部にイメージマップがあり、対応するテキストリンクがページの下部にあるページの例です。
<!DOCTYPE HTML>
< HTML LANG = "EN" >
< TITLE > Babies™: Toys</ TITLE >
< HEADER >
< H1 > Toys</ H1 >
< IMG SRC = "/images/menu.gif"
ALT = "Babies™ navigation menu. Select a department to go to its page."
USEMAP = "#NAV" >
</ HEADER >
...
< FOOTER >
< MAP NAME = "NAV" >
< P >
< A HREF = "/clothes/" > Clothes</ A >
< AREA ALT = "Clothes" COORDS = "0,0,100,50" HREF = "/clothes/" > |
< A HREF = "/toys/" > Toys</ A >
< AREA ALT = "Toys" COORDS = "100,0,200,50" HREF = "/toys/" > |
< A HREF = "/food/" > Food</ A >
< AREA ALT = "Food" COORDS = "200,0,300,50" HREF = "/food/" > |
< A HREF = "/books/" > Books</ A >
< AREA ALT = "Books" COORDS = "300,0,400,50" HREF = "/books/" >
</ P >
</ MAP >
</ FOOTER >
area要素すべての現行エンジンでサポートされています。
すべての現行エンジンでサポートされています。
map要素の祖先が存在する場合のみ。
alt — 画像が利用できない場合の代替テキスト
coords — イメージマップに作成される形状の座標
shape — イメージマップに作成される形状の種類
href — ハイパーリンクのアドレス
target — ナビゲーブルのハイパーリンク ナビゲーション
download —
リソースをナビゲートする代わりにダウンロードするかどうか、およびその場合のファイル名
ping — URLにpingを送信
rel — ハイパーリンクを含む文書の位置と宛先リソースの間の関係
referrerpolicy
— 要素によって開始された参照ポリシー。
href属性がある場合: 著者向け; 実装者向け。
[Exposed =Window ]
interface HTMLAreaElement : HTMLElement {
[HTMLConstructor ] constructor ();
[CEReactions ] attribute DOMString alt ;
[CEReactions ] attribute DOMString coords ;
[CEReactions ] attribute DOMString shape ;
[CEReactions ] attribute DOMString target ;
[CEReactions ] attribute DOMString download ;
[CEReactions ] attribute USVString ping ;
[CEReactions ] attribute DOMString rel ;
[SameObject , PutForwards =value ] readonly attribute DOMTokenList relList ;
[CEReactions ] attribute DOMString referrerPolicy ;
// also has obsolete members
};
HTMLAreaElement includes HTMLHyperlinkElementUtils ;
area要素は、テキストを伴ったハイパーリンクと画像マップ上の対応する領域、または画像マップ上の無効な領域のいずれかを表します。
親ノードを持つarea要素には、map要素の祖先が必要です。
もしarea要素にhref属性がある場合、そのarea要素はハイパーリンクを表します。この場合、alt属性が必要です。これはハイパーリンクのテキストを指定します。この値は、他のハイパーリンクのために指定されたテキストや、画像の代替テキストと共に提示されたときに、画像自体なしでハイパーリンクが提供するのと同じ種類の選択肢をユーザーに提供するテキストでなければなりません。もし同じ画像マップ内に同じリソースを指す別のarea要素があり、そのalt属性が空でない場合、alt属性は空白のままにすることができます。
もしarea要素にhref属性がない場合、その要素が表す領域は選択できず、alt属性は省略されなければなりません。
いずれの場合も、shapeおよびcoords属性はその領域を指定します。
shape属性は列挙属性であり、次のキーワードと状態を持ちます。
| キーワード | 準拠 | 状態 | 簡単な説明 |
|---|---|---|---|
circle
| 円状態 | coords属性にちょうど3つの整数を使用して円を指定します。
| |
circ
| いいえ | ||
default
| デフォルト状態 | このエリアは画像全体です。(coords属性は使用されません。)
| |
poly
| 多角形状態 | coords属性に少なくとも6つの整数を使用して多角形を指定します。
| |
polygon
| いいえ | ||
rect
| 矩形状態 | coords属性にちょうど4つの整数を使用して矩形を指定します。
| |
rectangle
| いいえ |
属性の欠落値のデフォルトと無効値のデフォルトは、いずれも矩形状態です。
coords属性は、指定されている場合、有効な浮動小数点数のリストを含んでいる必要があります。この属性は、shape属性で記述された形状の座標を指定します。この属性の処理は画像マップの処理モデルの一部として説明されています。
円状態では、area要素はcoords属性を持つ必要があり、3つの整数が含まれている必要があります。最後の整数は非負でなければなりません。最初の整数は画像の左端から円の中心までの距離を表し、2番目の整数は画像の上端から円の中心までの距離を表し、3番目の整数は円の半径を表します。
デフォルト状態では、area要素はcoords属性を持つことができません。(エリアは画像全体です。)
多角形状態では、area要素はcoords属性を持ち、少なくとも6つの整数が含まれている必要があります。整数の数は偶数でなければなりません。各整数のペアは、画像の左端および上端からの距離を表し、すべての座標はポリゴンの頂点を順に表します。
矩形状態では、area要素はcoords属性を持ち、ちょうど4つの整数が含まれている必要があります。最初の整数は3番目の整数より小さく、2番目の整数は4番目の整数より小さくなければなりません。この4つの整数はそれぞれ、画像の左端から矩形の左側までの距離、上端から矩形の上端までの距離、左端から矩形の右側までの距離、および上端から矩形の下端までの距離を表します。
ユーザーエージェントがハイパーリンクのフォローやハイパーリンクのダウンロードを許可する場合、area要素を使用して作成されたリンクは、href、target、download、およびping属性によってリンクのフォロー方法が決定されます。rel属性は、リンクをフォローする前にターゲットリソースの性質をユーザーに示すために使用できます。
target、download、ping、rel、およびreferrerpolicy属性は、href属性が存在しない場合、省略しなければなりません。
itemprop属性がarea要素に指定されている場合、href属性も指定されなければなりません。
すべての現行エンジンでサポートされています。
IDL属性alt、coords、shape、target、
download、ping、およびrelは、それぞれ同名の対応するコンテンツ属性を反映しなければなりません。
すべての現行エンジンでサポートされています。
IDL属性relListは、relコンテンツ属性を反映しなければなりません。
HTMLAreaElement/referrerPolicy
すべての現行エンジンでサポートされています。
IDL属性referrerPolicyは、referrerpolicyコンテンツ属性を反映し、既知の値のみに制限されなければなりません。
イメージマップは、画像上の幾何学的な領域をハイパーリンクに関連付けることができます。
img要素の形式で画像が表示されている場合、map要素の形式でイメージマップに関連付けることができます。usemap属性が指定されている場合、img要素にusemap属性を指定することで、イメージマップに関連付けることができます。
次のような画像を考えてみてください:

クリック可能な領域を色付きの部分に限定したい場合、次のように行うことができます:
< p >
図形を選んでください:
< img src = "shapes.png" usemap = "#shapes"
alt = "四つの図形が利用可能です:赤い空の四角形、緑の円、青い三角形、黄色の四方星形。" >
< map name = "shapes" >
< area shape = rect coords = "50,50,100,100" > <!-- 赤い箱の穴 -->
< area shape = rect coords = "25,25,125,125" href = "red.html" alt = "赤い箱。" >
< area shape = circle coords = "200,75,50" href = "green.html" alt = "緑の円。" >
< area shape = poly coords = "325,25,262,125,388,125" href = "blue.html" alt = "青い三角形。" >
< area shape = poly coords = "450,25,435,60,400,75,435,90,450,125,465,90,500,75,465,60"
href = "yellow.html" alt = "黄色の星形。" >
</ map >
</ p >
もし、img要素に
usemap属性が指定されている場合、ユーザーエージェントは以下のように処理する必要があります:
属性の値をハッシュ名参照の解析ルールを使用して、
map要素に解析し、
その要素をコンテキストノードとして使用します。これにより、要素(map)またはnullが返されます。
nullが返された場合は、終了します。画像はイメージマップと関連付けられていません。
それ以外の場合、ユーザーエージェントはarea要素をすべて収集し、
それらがareasとなります。
イメージマップを構成するarea要素のリストを取得した後、
インタラクティブなユーザーエージェントはそのリストを2つの方法のいずれかで処理する必要があります。
ユーザーエージェントがimg要素が表すテキストを表示するつもりである場合、
次の手順を使用する必要があります。
areas内のarea要素で
alt属性がないもの、または
alt属性の値が空文字列であるものを、
同じ値を持つ別のarea要素が
href属性にあり、
非空のalt属性を持っている場合に削除します。
残りのarea要素は
ハイパーリンクを表します。これらのハイパーリンクはすべて、
imgのテキストに関連する形で
ユーザーに提供されるべきです。
この文脈では、ユーザーエージェントはareaおよび
img要素に指定されていない
alt属性や、alt属性が空文字列やその他の非表示テキストである場合に、
著者提供のテキストが不足していることを示すための
実装定義の方法でそれらを表現することができます。
ユーザーエージェントが画像を表示し、画像とのインタラクションを通じてハイパーリンクを選択できるようにするつもりである場合、
画像はareas内のarea要素から取得した
レイヤー化された形状のセットと関連付けられる必要があります。これらの形状はツリー順序の逆順に
処理されます(つまり、map内で最後に指定されたarea要素が
最下層の形状となり、map内で最初に指定された要素が最上層の形状となります)。
areas内の各area要素は、
画像にレイヤーを追加するために以下のように処理される必要があります:
要素のshape属性が
表す状態を確認します。
要素のcoords属性が
存在する場合、浮動小数点数のリストを解析するルールを使用して解析し、
結果をcoordsリストとします。属性が存在しない場合は、coordsリストを空のリストとします。
coordsリストの項目数が、area要素の現在の状態に対応する以下の表で示されている最小数に満たない場合、
形状は空であり、終了します。
| 状態 | 最小項目数 |
|---|---|
| 円形状態 | 3 |
| デフォルト状態 | 0 |
| 多角形状態 | 6 |
| 矩形状態 | 4 |
次のリストのエントリに従って、shape属性の状態に対応する
coordsリスト内の過剰項目をチェックします:
shape属性が
矩形状態を表し、
リストの最初の数字がリストの3番目の数字よりも大きい場合は、その2つの数字を入れ替えます。
shape属性が
矩形状態を表し、
リストの2番目の数字がリストの4番目の数字よりも大きい場合は、その2つの数字を入れ替えます。
今、要素が表す形状は、以下のリストでshape属性の状態に対応する
エントリに記述されたものです:
xをcoordsの最初の数字とし、yを2番目の数字とし、 rを3番目の数字とします。
形状は、xが左端からyが上端からそれぞれr離れた位置に中心を持ち、 rが半径の円です。
形状は、画像全体を覆う矩形です。
xiをcoordsの(2i)番目のエントリとし、 yiをcoordsの(2i+1)番目のエントリとします (coordsの最初のエントリがインデックス0のものとします)。
座標を(xi, yi)とし、 これを画像の左上から測定した CSSピクセル で解釈します。 iの値は0から(N/2)-1までの整数値で、 Nはcoords内の項目数です。
形状は頂点が座標で与えられた多角形で、その内部は偶奇規則を使用して確立されます。 [GRAPHICS]
x1をcoordsの最初の数字とし、 y1を2番目の数字とし、 x2を3番目の数字とし、 y2を4番目の数字とします。
形状は、左上隅の座標が(x1, y1)で、 右下隅の座標が(x2, y2)である矩形です。 これらの座標は画像の左上から測定した CSSピクセル で解釈されます。
歴史的な理由から、座標はCSSの幅および
高さプロパティ(または、非CSSブラウザの場合はimg要素のwidthおよびheight属性)によって引き伸ばされた後の表示された画像に対して相対的に解釈される必要があります。
ブラウザのズーム機能やCSSやSVGを使用して適用される変形は、座標には影響しません。
上記のアルゴリズムに従って一連のレイヤー化された形状に関連付けられた画像とのポインティングデバイスによるインタラクションは、ポインティングデバイスが指示したポイントを覆う最上位の形状があれば、まずその形状に対して、なければ画像要素自体に対して、関連するユーザーインタラクションイベントが最初に発火する必要があります。ユーザーエージェントはまた、area要素で表される
ハイパーリンクを個別に選択およびアクティベートできるようにすることもできます(例:キーボードを使用して)。
map要素(およびその
area要素)は、複数のimg要素に関連付けることができるため、area要素がドキュメント内の複数のフォーカス可能な領域に対応することが可能です。
イメージマップはライブであり、DOMが変更された場合、ユーザーエージェントはイメージマップのアルゴリズムを再実行したかのように動作する必要があります。
HTML/HTML5/HTML5_Parser#Inline_SVG_and_MathML_support
すべての現行エンジンでサポートされています。
MathML math 要素は、この仕様書のコンテンツモデルにおいて 埋め込みコンテンツ、フレージングコンテンツ、フローコンテンツ、および 明示的コンテンツ カテゴリーに分類されます。
MathML annotation-xml 要素が HTML 名前空間 の要素を含む場合、これらの要素はすべて フローコンテンツ でなければなりません。
MathML トークン要素 (mi、mo、mn、ms、および mtext) が HTML 要素の子孫である場合、それらは フレージングコンテンツ の要素を HTML 名前空間
から含むことができます。
ユーザーエージェントは、MathML 要素のコンテンツモデルがストレートテキストを許可しない場合、その要素内の他のテキストを、MathML コンテンツモデル、レイアウト、およびレンダリングの目的で実際には MathML mtext
要素で囲まれているかのように扱わなければなりません。(ただし、そのようなテキストは準拠していません。)
ユーザーエージェントは、コンテンツがその要素のコンテンツモデルと一致しない MathML 要素があった場合、MathML レイアウトとレンダリングの目的で、それが適切なエラーメッセージを含む MathML merror 要素に置き換えられたかのように振る舞わなければなりません。
MathML 要素の意味論は MathML および その他の適用可能な仕様書 によって定義されています。[MATHML]
以下は、HTML ドキュメントで MathML を使用する例です。
<!DOCTYPE html>
< html lang = "en" >
< head >
< title > The quadratic formula</ title >
</ head >
< body >
< h1 > The quadratic formula</ h1 >
< p >
< math >
< mi > x</ mi >
< mo > =</ mo >
< mfrac >
< mrow >
< mo form = "prefix" > −</ mo > < mi > b</ mi >
< mo > ±</ mo >
< msqrt >
< msup > </ mi > b</ mi > </ mn > 2</ mn > </ msup >
</ mo > −</ mo >
</ mn > 4</ mn > </ mo > </ mo > </ mi > a</ mi > </ mo > </ mo > </ mi > c</ mi >
</ msqrt >
</ mrow >
</ mrow >
</ mn > 2</ mn > </ mo > </ mo > </ mi > a</ mi >
</ mrow >
</ mfrac >
</ math >
</ p >
</ body >
</ html >
HTML/HTML5/HTML5_Parser#Inline_SVG_and_MathML_support
すべての現行エンジンでサポートされています。
SVG
svg 要素は、この仕様書のコンテンツモデルにおいて 埋め込みコンテンツ、フレージングコンテンツ、フローコンテンツ、および
明示的コンテンツ カテゴリーに分類されます。
SVG foreignObject 要素が HTML 名前空間
の要素を含む場合、これらの要素はすべて フローコンテンツ でなければなりません。
SVG
title 要素の HTML ドキュメント 内のコンテンツモデルは フレージングコンテンツ です。
(これは SVG 2 による要件をさらに制約します。)
SVG 要素の意味論は SVG 2 および その他の適用可能な 仕様書 によって定義されています。[SVG]
doc = iframe.getSVGDocument()
doc = embed.getSVGDocument()
doc = object.getSVGDocument()
Document オブジェクトを返します。対象となる要素が
iframe、
embed、または object であり、これらが
SVG を埋め込むために使用されている場合です。
getSVGDocument() メソッドの手順は次のとおりです。
document を this の コンテンツドキュメント とします。
もし document が null でなく、かつ XML ファイルのページ読み込み処理モデル
によって作成されたものであり、かつ リソースの推定タイプ が image/svg+xml であった場合には、document
を返します。
null を返します。
著者要件: img、iframe、
embed、object、
video、source要素に対して、
width属性と
height属性が指定される場合、その親が
picture要素であり、
type属性が
画像ボタン状態にある場合、
input要素に対して、視覚的なコンテンツの次元
(それぞれの幅と高さ)を、出力媒体の標準方向に対してCSSピクセルで指定することができます。これらの属性が指定される場合、その値は
有効な非負整数でなければなりません。
指定された次元は、リソース自体で指定された次元と異なる場合があります。これは、リソースがCSSピクセルの解像度と異なる解像度を持っている可能性があるためです。 (画面では、CSSピクセルは96ppiの解像度を持ちますが、一般的にCSSピクセルの解像度は閲覧距離に依存します。) 両方の属性が指定される場合、次のいずれかの条件が真でなければなりません:
ターゲット比とは、リソース内の
自然幅と自然高さ
の比率です。指定された幅と指定された高さは、それぞれ
widthと
height属性の値です。
対象リソースに自然幅と自然高さ が両方存在しない場合、これらの2つの属性は省略しなければなりません。
両方の属性が0である場合、それは要素がユーザー向けでないことを示しています(例:ページビューをカウントするサービスの一部かもしれません)。
次元属性は画像を引き伸ばすために使用されることを意図していません。
ユーザーエージェント要件: ユーザーエージェントは、レンダリングのヒントとして これらの属性を使用することが期待されています。
すべての現行エンジンでサポートされています。
すべての現行エンジンでサポートされています。
widthおよびheightIDL属性は、iframe、
embed、
object、
source、
およびvideo
要素に対して、それぞれ同名のコンテンツ属性を反映する必要があります。
iframe、
embed、
およびobject
に対するIDL属性はDOMStringです。videoと
sourceのIDL属性はunsigned
longです。
imgおよび
input要素に対する対応するIDL属性は、それぞれの要素の他の動作にやや特有であるため、それぞれの要素のセクションで定義されています。
table要素全ての現行エンジンでサポートされています。
全ての現行エンジンでサポートされています。
caption要素が続き、ゼロまたは複数のcolgroup要素が続き、オプションでthead要素が続き、ゼロまたは複数のtbody要素または1つ以上のtr要素が続き、オプションでtfoot要素が続き、オプションで1つまたは複数のスクリプトサポート要素が混在します。
[Exposed =Window ]
interface HTMLTableElement : HTMLElement {
[HTMLConstructor ] constructor ();
[CEReactions ] attribute HTMLTableCaptionElement ? caption ;
HTMLTableCaptionElement createCaption ();
[CEReactions ] undefined deleteCaption ();
[CEReactions ] attribute HTMLTableSectionElement ? tHead ;
HTMLTableSectionElement createTHead ();
[CEReactions ] undefined deleteTHead ();
[CEReactions ] attribute HTMLTableSectionElement ? tFoot ;
HTMLTableSectionElement createTFoot ();
[CEReactions ] undefined deleteTFoot ();
[SameObject ] readonly attribute HTMLCollection tBodies ;
HTMLTableSectionElement createTBody ();
[SameObject ] readonly attribute HTMLCollection rows ;
HTMLTableRowElement insertRow (optional long index = -1);
[CEReactions ] undefined deleteRow (long index );
// also has obsolete members
};
table要素は、表モデルに参加します。表にはその子孫によって与えられる行、列、セルがあります。行と列はグリッドを形成し、表のセルはそのグリッドを完全にカバーし、重複は許されません。
この適合要件が満たされているかどうかを判断するための正確な規則は、表モデルの説明で説明されています。
著者は、複雑な表の解釈方法を説明する情報を提供することが推奨されます。そのような情報を提供する方法に関するガイダンスは以下に記載されています。
表はレイアウト補助として使用してはなりません。歴史的に、いくつかのウェブ著者はHTMLの表をページレイアウトを制御する手段として誤用してきました。この使用法は適合しません。なぜなら、そのようなドキュメントから表データを抽出しようとするツールは非常に混乱する結果を得るからです。特に、スクリーンリーダーなどのアクセシビリティツールのユーザーは、レイアウトに使用された表のページをナビゲートするのが非常に難しいと感じる可能性があります。
HTML表をレイアウトに使用する代替手段として、CSSグリッドレイアウト、CSSフレックスボックスレイアウト("flexbox")、CSSマルチカラムレイアウト、CSSポジショニング、CSSテーブルモデルなどがあります。[CSS]
表は理解しやすくナビゲートしやすくするために、セルを明確に区別するべきです。ユーザーエージェントが表を(非適合の)レイアウト表として分類していない限り、セルを明確に区別するべきです。
著者および実装者は、表をユーザーにとってナビゲートしやすくするために、表デザインの手法のいくつかを使用することを検討することが推奨されます。
特に任意のコンテンツで表分析を行うユーザーエージェントは、どの表が実際にデータを含み、どの表が単にレイアウトに使用されているかを判断するためのヒューリスティックを見つけることが推奨されます。この仕様は正確なヒューリスティックを定義していませんが、以下は可能な指標として提案されています。
| 特徴 | 示唆 |
|---|---|
role属性にpresentationの値が使用されている
| おそらくレイアウト表 |
border属性に0の非適合値が使用されている
| おそらくレイアウト表 |
cellspacingとcellpadding属性に0の非適合値が使用されている
| おそらくレイアウト表 |
caption、thead、またはth要素が使用されている
| おそらく非レイアウト表 |
headersおよびscope属性が使用されている
| おそらく非レイアウト表 |
border属性に0以外の値が使用されている
| おそらく非レイアウト表 |
| CSSで設定された明示的な目に見えるボーダー | おそらく非レイアウト表 |
summary属性が使用されている
| 良い指標ではありません(歴史的にレイアウト表と非レイアウト表の両方にこの属性が付与されています) |
上記の提案が間違っている可能性は十分にあります。実装者は、レイアウト表の検出ヒューリスティックを作成しようとした際の経験に基づいてフィードバックを提供することが推奨されます。
table要素に(非適合の)summary属性があり、ユーザーエージェントが表をレイアウト表として分類していない場合、ユーザーエージェントはその属性の内容をユーザーに報告してもかまいません。
table.caption [ = value ]
すべての現在のエンジンでサポートされています。
テーブルのcaption要素を返します。
設定可能で、caption要素を置き換えます。
caption = table.createCaption()
HTMLTableElement/createCaption
すべての現在のエンジンでサポートされています。
テーブルにcaption要素があることを保証し、返します。
table.deleteCaption()
HTMLTableElement/deleteCaption
すべての現在のエンジンでサポートされています。
テーブルにcaption要素がないことを保証します。
table.tHead [ = value ]
すべての現在のエンジンでサポートされています。
テーブルのthead要素を返します。
設定可能で、thead要素を置き換えます。新しい値がthead要素でない場合、"HierarchyRequestError"
DOMExceptionをスローします。
thead = table.createTHead()
すべての現在のエンジンでサポートされています。
テーブルにthead要素があることを保証し、返します。
table.deleteTHead()
すべての現在のエンジンでサポートされています。
テーブルにthead要素がないことを保証します。
table.tFoot [ = value ]
すべての現在のエンジンでサポートされています。
テーブルのtfoot要素を返します。
設定可能で、tfoot要素を置き換えます。新しい値がtfoot要素でない場合、"HierarchyRequestError"
DOMExceptionをスローします。
tfoot = table.createTFoot()
すべての現在のエンジンでサポートされています。
テーブルにtfoot要素があることを保証し、返します。
table.deleteTFoot()
すべての現在のエンジンでサポートされています。
テーブルにtfoot要素がないことを保証します。
table.tBodies
すべての現在のエンジンでサポートされています。
テーブルのHTMLCollectionを返します。
tbody要素の
tbody = table.createTBody()
すべての現在のエンジンでサポートされています。
テーブルにtbody要素を作成し、挿入して返します。
table.rows
すべての現在のエンジンでサポートされています。
テーブルのHTMLCollectionのtr要素を返します。
tr = table.insertRow([ index ])
すべての現在のエンジンでサポートされています。
必要に応じてtbodyとともにtr要素を作成し、それらをテーブルの引数で指定された位置に挿入し、trを返します。
位置はテーブル内の行に対して相対的です。引数が省略された場合のデフォルトであるインデックス−1は、テーブルの最後に挿入することと同等です。
指定された位置が−1より小さいか、行の数より大きい場合、"IndexSizeError" DOMExceptionをスローします。
table.deleteRow(index)
すべての現在のエンジンでサポートされています。
テーブル内の指定された位置にあるtr要素を削除します。
位置はテーブル内の行に対して相対的です。インデックス−1はテーブルの最後の行を削除することに相当します。
指定された位置が−1より小さいか、最後の行のインデックスより大きい場合、または行がない場合、"IndexSizeError" DOMExceptionをスローします。
次のすべての属性およびメソッドの定義において、要素がテーブル作成される場合、それは要素を作成することを意味します。指定されたローカル名とノードドキュメント、およびHTML名前空間を使用して、table要素のノードを指定します。
captionIDL属性は、取得時にcaption要素を返さなければなりません。table要素の最初の子要素が存在する場合、それを返し、存在しない場合はnullを返します。設定時には、最初のcaption要素が削除され、新しい値がnullでない場合は、それをtable要素の最初のノードとして挿入しなければなりません。
createCaption()メソッドは、caption要素を返さなければなりません。table要素の最初の子要素が存在する場合、それを返し、存在しない場合は新しいcaption要素をテーブル作成し、table要素の最初のノードとして挿入し、それを返さなければなりません。
deleteCaption()メソッドは、caption要素を削除しなければなりません。table要素の最初の子要素が存在する場合、それを削除しなければなりません。
tHeadIDL属性は、取得時にthead要素を返さなければなりません。table要素の最初の子要素が存在する場合、それを返し、存在しない場合はnullを返します。設定時に新しい値がnullまたはthead要素の場合、最初のthead要素を削除し、新しい値がnullでない場合はtable要素の最初の要素の直前に挿入しなければなりません。それがcaption要素でもcolgroup要素でもない場合、もしくは該当する要素がない場合はテーブルの最後に挿入します。新しい値がnullでもthead要素でもない場合、"HierarchyRequestError" DOMExceptionがスローされなければなりません。
createTHead()メソッドは、table要素の最初のthead要素の子要素を返さなければなりません。もし存在しない場合は、新しいthead要素をtable-createdし、table要素内でcaption要素でもcolgroup要素でもない最初の要素の直前、またはそのような要素がない場合はテーブルの最後に挿入し、その新しい要素を返さなければなりません。
deleteTHead()メソッドは、thead要素を削除しなければなりません。table要素の最初の子要素が存在する場合、それを削除しなければなりません。
tFootIDL属性は、取得時にtfoot要素を返さなければなりません。table要素の最初の子要素が存在する場合、それを返し、存在しない場合はnullを返します。設定時に新しい値がnullまたはtfoot要素の場合、最初のtfoot要素を削除し、新しい値がnullでない場合はテーブルの最後に挿入しなければなりません。新しい値がnullでもtfoot要素でもない場合、"HierarchyRequestError" DOMExceptionがスローされなければなりません。
createTFoot()メソッドは、table要素の最初のtfoot要素の子要素を返さなければなりません。もし存在しない場合は、新しいtfoot要素をtable-createdし、テーブルの最後に挿入し、その新しい要素を返さなければなりません。
deleteTFoot()メソッドは、tfoot要素を削除しなければなりません。table要素の最初の子要素が存在する場合、それを削除しなければなりません。
tBodies属性は、HTMLCollectionを返さなければなりません。それは、tableノードにルートを持ち、フィルターはtbody要素のみを一致させ、それらはtable要素の子要素です。
createTBody()メソッドは、新しいtbody要素をテーブル作成し、それをtable要素内の最後のtbody要素の後に挿入するか、table要素がtbody要素を持たない場合はテーブルの最後に挿入し、新しいtbody要素を返さなければなりません。
rows属性は、HTMLCollectionを返さなければなりません。それは、tableノードにルートを持ち、フィルターはtr要素のみを一致させ、それらはtable要素の子要素、またはthead、tbody、またはtfoot要素の子要素です。コレクション内の要素は、theadの親が最初に含まれ、それがtbodyまたはtable要素の親が含まれ、最後にtfootの親が含まれ、それがツリー順に配置されます。
insertRow(index)メソッドの動作は、テーブルの状態によって異なります。呼び出されたとき、このメソッドは、以下の条件リストに記載されたテーブルの状態とindex引数を説明する最初の項目に従って動作しなければなりません。
rowsコレクション内の要素数を超えている場合:
IndexSizeError"DOMExceptionをスローしなければなりません。
rowsコレクションに要素が一つもなく、かつtableにtbody要素が含まれていない場合:
tbody要素をテーブル作成し、次にtr要素をテーブル作成し、その後tr要素をtbody要素に追加し、次にtbody要素をtable要素に追加し、最終的にtr要素を返さなければなりません。
rowsコレクションに要素が一つもない場合:
tr要素をテーブル作成し、それをテーブル内の最後のtbody要素に追加し、そのtr要素を返さなければなりません。
rowsコレクション内の項目数に等しい場合:
tr要素をテーブル作成し、次にrowsコレクション内の最後のtr要素の親に追加し、そして新たに作成されたtr要素を返さなければなりません。
tr要素をテーブル作成し、それを同じ親内のrowsコレクション内のindex番目のtr要素の直前に挿入し、最終的に新たに作成されたtr要素を返さなければなりません。
deleteRow(index)メソッドが呼び出された場合、ユーザーエージェントは次の手順を実行しなければなりません。
rowsコレクション内の要素数以上の場合、"IndexSizeError"DOMExceptionをスローしなければなりません。
rowsコレクション内の最後の要素をその親から削除するか、rowsコレクションが空の場合は何もしません。
rowsコレクション内のindex番目の要素をその親から削除しなければなりません。
以下は、数独パズルをマークアップするためにテーブルを使用した例です。このようなテーブルには見出しが必要ないことに注意してください。
< style >
# sudoku { border-collapse : collapse ; border : solid thick ; }
# sudoku colgroup , table # sudoku tbody { border : solid medium ; }
# sudoku td { border : solid thin ; height : 1.4 em ; width : 1.4 em ; text-align : center ; padding : 0 ; }
</ style >
< h1 > Today's Sudoku</ h1 >
< table id = "sudoku" >
< colgroup >< col >< col >< col >
< colgroup >< col >< col >< col >
< colgroup >< col >< col >< col >
< tbody >
< tr > < td > 1 < td > < td > 3 < td > 6 < td > < td > 4 < td > 7 < td > < td > 9
< tr > < td > < td > 2 < td > < td > < td > 9 < td > < td > < td > 1 < td >
< tr > < td > 7 < td > < td > < td > < td > < td > < td > < td > < td > 6
< tbody >
< tr > < td > 2 < td > < td > 4 < td > < td > 3 < td > < td > 9 < td > < td > 8
< tr > < td > < td > < td > < td > < td > < td > < td > < td > < td >
< tr > < td > 5 < td > < td > < td > 9 < td > < td > 7 < td > < td > < td > 1
< tbody >
< tr > < td > 6 < td > < td > < td > < td > 5 < td > < td > < td > < td > 2
< tr > < td > < td > < td > < td > < td > 7 < td > < td > < td > < td >
< tr > < td > 9 < td > < td > < td > 8 < td > < td > 2 < td > < td > < td > 5
</ table >
最初の行にヘッダーがあり、最初の列にヘッダーがあるセルのグリッドだけで構成されているテーブルだけでなく、読者が内容を理解するのに苦労する可能性のある一般的なテーブルについても、著者はテーブルを紹介する説明情報を含めるべきです。この情報はすべてのユーザーにとって有用ですが、特にテーブルを見ることができないユーザー、たとえばスクリーンリーダーのユーザーにとって有用です。
このような説明情報は、テーブルの目的を紹介し、基本的なセル構造の概要を示し、傾向やパターンを強調し、一般的にユーザーがテーブルをどのように使用するかを教えるべきです。
例えば、次のテーブル:
| 否定的 | 特徴 | 肯定的 |
|---|---|---|
| 悲しい | 気分 | 幸せ |
| 不合格 | 成績 | 合格 |
...は、テーブルの配置方法を説明するような説明があると役立つかもしれません。「特徴は第2列に示されており、左列に否定的な側面があり、右列に肯定的な側面があります。」のような説明です。
この情報を含める方法はいろいろあります。例えば:
< p > 以下のテーブルでは、特徴は第2列に示されており、左列に否定的な側面があり、右列に肯定的な側面があります。</ p >
< table >
< caption > 肯定的および否定的な側面を持つ特徴</ caption >
< thead >
< tr >
< th id = "n" > 否定的
< th > 特徴
< th > 肯定的
</ thead >
< tr >
< td headers = "n r1" > 悲しい
< th id = "r1" > 気分
< td > 幸せ
</ tr >
< td headers = "n r2" > 不合格
< th id = "r2" > 成績
</ td > 合格
</ table >
caption内
< table >
< caption >
< strong > 肯定的および否定的な側面を持つ特徴。</ strong >
< p > 特徴は第2列に示されており、左列に否定的な側面があり、右列に肯定的な側面があります。</ p >
</ caption >
</ thead >
< tr >
< th id = "n" > 否定的
< th > 特徴
< th > 肯定的
</ tbody >
</ tr >
< td headers = "n r1" > 悲しい
< th id = "r1" > 気分
< td > 幸せ
</ tr >
< td headers = "n r2" > 不合格
< th id = "r2" > 成績
</ td > 合格
</ table >
caption内の
details要素で
< table >
< caption >
< strong > 肯定的および否定的な側面を持つ特徴。</ strong >
< details >
< summary > ヘルプ</ summary >
< p > 特徴は第2列に示されており、左列に否定的な側面があり、右列に肯定的な側面があります。</ p >
</ details >
</ caption >
</ thead >
</ tr >
< th id = "n" > 否定的
< th > 特徴
< th > 肯定的
</ tbody >
</ tr >
< td headers = "n r1" > 悲しい
< th id = "r1" > 気分
< td > 幸せ
</ tr >
< td headers = "n r2" > 不合格
< th id = "r2" > 成績
</ td > 合格
</ table >
figure内に
< figure >
< figcaption > 肯定的および否定的な側面を持つ特徴</ figcaption >
< p > 特徴は第2列に示されており、左列に否定的な側面があり、右列に肯定的な側面があります。</ p >
</ table >
</ thead >
< tr >
< th id = "n" > 否定的
< th > 特徴
< th > 肯定的
</ tbody >
</ tr >
</ td headers = "n r1" > 悲しい
< th id = "r1" > 気分
< td > 幸せ
</ tr >
< td headers = "n r2" > 不合格
< th id = "r2" > 成績
</ td > 合格
</ table >
</ figure >
figureの
figcaption内に
< figure >
< figcaption >
< strong > 肯定的および否定的な側面を持つ特徴</ strong >
< p > 特徴は第2列に示されており、左列に否定的な側面があり、右列に肯定的な側面があります。</ p >
</ figcaption >
</ table >
</ thead >
< tr >
< th id = "n" > 否定的
< th > 特徴
< th > 肯定的
</ tbody >
</ tr >
</ td headers = "n r1" > 悲しい
< th id = "r1" > 気分
< td > 幸せ
</ tr >
< td headers = "n r2" > 不合格
< th id = "r2" > 成績
</ td > 合格
</ table >
</ figure >
著者は、これらの技術の他にも、またはそれらの組み合わせを適切に使用することができます。
もちろん、テーブルのレイアウトを説明する記述を書くよりも、説明が不要になるようにテーブルを調整するのが最良の選択です。
上記の例で使用されているテーブルの場合、テーブルを簡単に再配置するだけで、説明が不要になると同時に、headers
属性を使用する必要もなくなります。
< table >
< caption > 肯定的および否定的な側面を持つ特徴</ caption >
< thead >
< tr >
< th > 特徴
< th > 否定的
< th > 肯定的
</ tbody >
</ tr >
< th > 気分
< td > 悲しい
< td > 幸せ
</ tr >
< th > 成績
< td > 不合格
< td > 合格
</ table >
優れたテーブルデザインは、テーブルをより読みやすく、使いやすくするための重要な要素です。
視覚メディアでは、列と行の境界線を提供し、交互に行の背景色を変えることで、複雑なテーブルをより読みやすくすることが非常に効果的です。
数値の多いテーブルでは、等幅フォントを使用することで、特にユーザーエージェントが境界線をレンダリングしない状況で、ユーザーがパターンを見やすくすることができます。(残念ながら、歴史的な理由から、テーブルの境界線をレンダリングしないことが一般的なデフォルトとなっています。)
音声メディアでは、テーブルのセルを読み上げる前に対応するヘッダーを報告し、テーブルの内容をソース順に直列化するのではなく、グリッド形式でテーブルをナビゲートできるようにすることで、セルを区別することができます。
著者はこれらの効果を実現するためにCSSを使用することが推奨されます。
ユーザーエージェントは、ページがCSSを使用しておらず、テーブルがレイアウトテーブルとして分類されていない場合、これらの技術を使用してテーブルをレンダリングすることが推奨されます。
caption
要素現在のすべてのエンジンでサポートされています。
現在のすべてのエンジンでサポートされています。
table 要素の最初の子要素として。
table
要素を含まない。
caption
要素の
終了タグは、
caption
要素が直後に ASCII
ホワイトスペースや
コメントが続かない場合、省略できます。
[Exposed =Window ]
interface HTMLTableCaptionElement : HTMLElement {
[HTMLConstructor ] constructor ();
// 廃止されたメンバーも含まれています
};
caption
要素は、親が table 要素である場合、その
タイトルを表します。
table
要素が figure
要素の唯一のコンテンツであり、
それ以外に figcaption
がある場合は、caption
要素は省略すべきです。
キャプションは、テーブルにコンテキストを提供し、理解を大幅に容易にすることができます。
例えば、次のテーブルを考えてみましょう:
| 1 | 2 | 3 | 4 | 5 | 6 | |
|---|---|---|---|---|---|---|
| 1 | 2 | 3 | 4 | 5 | 6 | 7 |
| 2 | 3 | 4 | 5 | 6 | 7 | 8 |
| 3 | 4 | 5 | 6 | 7 | 8 | 9 |
| 4 | 5 | 6 | 7 | 8 | 9 | 10 |
| 5 | 6 | 7 | 8 | 9 | 10 | 11 |
| 6 | 7 | 8 | 9 | 10 | 11 | 12 |
抽象的には、このテーブルは明確ではありません。しかし、キャプションでテーブルの番号(メインの文章で参照するため)を示し、その使用方法を説明すると、より理解しやすくなります。
< caption >
< p > Table 1.
< p > このテーブルは、2つの6面ダイスを振ったときの合計点を示しています。最初の行は最初のダイスの値を表し、最初の列は2番目のダイスの値を表します。合計は、2つのダイスの値に対応するセルに表示されます。
</ caption >
これにより、ユーザーにより多くのコンテキストが提供されます:
| 1 | 2 | 3 | 4 | 5 | 6 | |
|---|---|---|---|---|---|---|
| 1 | 2 | 3 | 4 | 5 | 6 | 7 |
| 2 | 3 | 4 | 5 | 6 | 7 | 8 |
| 3 | 4 | 5 | 6 | 7 | 8 | 9 |
| 4 | 5 | 6 | 7 | 8 | 9 | 10 |
| 5 | 6 | 7 | 8 | 9 | 10 | 11 |
| 6 | 7 | 8 | 9 | 10 | 11 | 12 |
colgroup
要素
現在のすべてのエンジンでサポートされています。
現在のすべてのエンジンでサポートされています。
table
要素の子要素として、caption
要素の後、thead、
tbody、tfoot、tr
要素の前に配置されます。
span
属性が存在する場合: なし。
span
属性が存在しない場合: 0個以上のcolおよびtemplate
要素を含みます。
colgroup
要素の開始タグは、colgroup
要素内の最初の要素がcol
要素である場合、かつその要素が別のcolgroup
要素の直後にない場合は省略できます。(要素が空の場合、省略できません。)
colgroup
要素の終了タグは、colgroup
要素が直後にASCII
ホワイトスペース
やコメントが続かない場合、省略できます。
span —
要素がまたがる列の数
[Exposed =Window ]
interface HTMLTableColElement : HTMLElement {
[HTMLConstructor ] constructor ();
[CEReactions ] attribute unsigned long span ;
// 廃止されたメンバーも含まれています
};
colgroup要素は、親要素が存在し、かつそれがtable要素である場合、そのtable内の1つ以上の列のグループを表します。
colgroup
要素にcol
要素が含まれていない場合、この要素にはspan
内容属性が指定される場合があり、その値は0より大きく1000以下の有効な非負整数でなければなりません。
colgroup
要素とそのspan
属性はテーブルモデルに参加します。
span
IDL 属性は同名の内容属性を反映しなければなりません。それは範囲[1,
1000]に制限され、そのデフォルト値は1です。
col
要素現在のすべてのエンジンでサポートされています。
colgroup
要素の子要素であり、span属性がない場合。
span — 要素がまたがる列の数
HTMLTableColElement
を使用します。これはcolgroup
要素に対して定義されています。
col要素が親を持ち、
その親がcolgroup
要素で、その親がtable
要素である場合、col
要素は、colgroup
が表す列グループ内の
1つ以上の列を表します。
この要素にはspan内容属性が指定される場合があり、その値は
0より大きく1000以下の有効な非負整数でなければなりません。
col 要素とその
span 属性はテーブルモデルに参加します。
tbody
要素現在のすべてのエンジンでサポートされています。
現在のすべてのエンジンでサポートされています。
table要素の子要素として、caption、
colgroup、
およびthead要素の後に配置されますが、tr要素がその
table要素の子でない場合に限ります。
trおよび
スクリプトサポート要素を含みます。
tbody要素の
開始タグは、tr要素が最初に含まれている場合、および
tbody、thead、
またはtfoot要素が省略された終了タグで直前に続いていない場合、省略できます。(要素が空の場合、省略できません。)
tbody要素の
終了タグは、tbodyまたはtfoot要素が直後に続いている場合、
または親要素にそれ以上コンテンツがない場合、省略できます。
[Exposed =Window ]
interface HTMLTableSectionElement : HTMLElement {
[HTMLConstructor ] constructor ();
[SameObject ] readonly attribute HTMLCollection rows ;
HTMLTableRowElement insertRow (optional long index = -1);
[CEReactions ] undefined deleteRow (long index );
// 廃止されたメンバーも含まれています
};
HTMLTableSectionElementインターフェースは、
theadおよびtfoot要素にも使用されます。
tbody要素は、親がtable要素である場合、そのテーブルのデータ本体を構成する
行のブロックを表します。
tbody.rows
このテーブルセクションのtr要素の
HTMLCollectionを返します。
tr = tbody.insertRow([ index ])
tr要素を作成し、
引数で指定された位置にこのテーブルセクションに挿入し、trを返します。
位置はテーブルセクション内の行に対して相対的です。引数が省略された場合のデフォルトであるインデックス−1は、テーブルセクションの最後に挿入することと同等です。
指定された位置が−1より小さいか、行数を超えている場合、"IndexSizeError"
DOMExceptionをスローします。
tbody.deleteRow(index)
このテーブルセクション内の指定された位置にあるtr要素を削除します。
位置はテーブルセクション内の行に対して相対的です。インデックス−1はテーブルセクションの最後の行を削除することと同等です。
指定された位置が−1より小さいか、最後の行のインデックスを超えている場合、または行が存在しない場合、"IndexSizeError"
DOMExceptionをスローします。
rows属性は、この要素でルート化された
HTMLCollectionを返さなければなりません。このフィルタは、この要素の子であるtr要素のみを一致させます。
insertRow(index)メソッドは以下のように動作しなければなりません:
indexが−1より小さいか、rowsコレクション内の要素数を超えている場合、
"IndexSizeError"
DOMExceptionをスローします。
それ以外の場合は、table rowをこの要素の子として、rowsコレクション内のindex番目のtr要素の直前に挿入します。
table rowを返します。
deleteRow(index)メソッドは、呼び出されたとき、次のように動作しなければなりません:
indexが−1より小さいか、rowsコレクション内の最後の行のインデックス以上である場合、
"IndexSizeError"
DOMExceptionをスローします。
indexが−1の場合、この要素からrowsコレクション内の最後の要素を削除するか、rowsコレクションが空である場合は何もしません。
thead
要素現在のすべてのエンジンでサポートされています。
table要素の子要素として、
caption要素および
colgroup要素の後に、
そしてtbody、
tfoot、
およびtr要素の前に配置されますが、
そのtable要素の子である
他のthead要素がない場合に限ります。
trおよび
スクリプトサポート要素を含みます。
thead要素の
終了タグは、tbodyまたは
tfoot要素が直後に続いている場合、省略できます。
HTMLTableSectionElement
を使用します。これはtbody要素に対して定義されています。
thead要素は、親がtable要素である場合、
そのテーブル要素の列ラベル(ヘッダ)と補助的な非ヘッダセルで構成される
行のブロックを表します。
この例は、thead要素の使用例を示しています。
th要素とtd要素の両方が
thead要素内で使用されていることに注目してください。
最初の行はヘッダで、2番目の行はテーブルの記入方法を説明しています。
< table >
< caption > School auction sign-up sheet </ caption >
< thead >
< tr >
< th >< label for = e1 > Name</ label >
< th >< label for = e2 > Product</ label >
< th >< label for = e3 > Picture</ label >
< th >< label for = e4 > Price</ label >
</ tr >
< td > Your name here
</ td >
< td > What are you selling?
</ td >
< td > Link to a picture
</ td >
< td > Your reserve price
</ tbody >
< tr >
</ td >
</ td >
</ td >
</ td >
</ tr >
</ table >
</ form id = f action = "/auction.cgi" >
</ input type = button name = add value = "Submit" >
</ form >
tfoot
要素現在のすべてのエンジンでサポートされています。
table要素の子要素として、
caption、
colgroup、
thead、
tbody、
およびtr要素の後に配置されますが、
そのtable要素の子である
他のtfoot要素がない場合に限ります。
trおよび
スクリプトサポート要素を含みます。
tfoot要素の
終了タグを省略できます。
HTMLTableSectionElement
を使用します。これはtbody要素に対して定義されています。
tfoot要素は、
親がtable要素である場合、
そのテーブル要素の列の要約(フッタ)で構成される
行のブロックを表します。
tr 要素
すべての現在のエンジンでサポートされています。
すべての現在のエンジンでサポートされています。
thead 要素の子要素として。
tbody 要素の子要素として。
tfoot 要素の子要素として。
table 要素の子要素として、
caption、colgroup、および
thead 要素の後に置きますが、
tbody 要素が table 要素の子要素でない場合に限ります。
td、th、およびスクリプトサポート要素を含みます。
tr 要素の終了タグは、tr
要素がすぐ後に続く場合、または親要素内にそれ以上のコンテンツがない場合に省略できます。
[Exposed =Window ]
interface HTMLTableRowElement : HTMLElement {
[HTMLConstructor ] constructor ();
readonly attribute long rowIndex ;
readonly attribute long sectionRowIndex ;
[SameObject ] readonly attribute HTMLCollection cells ;
HTMLTableCellElement insertCell (optional long index = -1);
[CEReactions ] undefined deleteCell (long index );
// also has obsolete members
};
tr 要素は 表します。 行 の
セルを テーブル内に配置します。
tr.rowIndex
現在のすべてのエンジンでサポートされています。
行の位置を返します。この位置はテーブルの 行
リスト内の位置です。
要素がテーブル内にない場合、−1 を返します。
tr.sectionRowIndex
テーブルセクションの 行 リスト内の行の位置を返します。
要素がテーブルセクション内にない場合、−1 を返します。
tr.cells
HTMLCollection
を返します。このコレクションは、行内の td および
th 要素の集まりです。
cell = tr.insertCell([ index ])
HTMLTableRowElement/insertCell
現在のすべてのエンジンでサポートされています。
td 要素を作成し、
テーブル行の指定された位置に挿入し、その td
を返します。
位置は行内のセルに対して相対的です。引数が省略された場合、デフォルトであるインデックス−1は、行の最後に挿入することと同等です。
指定された位置が−1より小さいか、セルの数より大きい場合、"IndexSizeError" DOMExceptionをスローします。
tr.deleteCell(index)
行内の指定された位置にある td または
th 要素を削除します。
位置は行内のセルに対して相対的です。インデックス−1は、行の最後のセルを削除することと同等です。
指定された位置が−1より小さいか、最後のセルのインデックスより大きい場合、またはセルがない場合、"IndexSizeError" DOMExceptionをスローします。
rowIndex
属性は、この要素が親 table 要素を持っている場合、
または親 tbody、thead、または
tfoot 要素と、その祖父母要素としての
table 要素を持っている場合、
この tr 要素がその
table 要素の 行 コレクション内でのインデックスを返す必要があります。
そのような table
要素がない場合、この属性は−1を返す必要があります。
sectionRowIndex 属性は、この要素が
親 table、tbody、thead、または tfoot 要素を持っている場合、
親要素の 行 コレクション内での tr
要素のインデックスを返す必要があります。
(テーブルの場合、それは HTMLTableElement の
行 コレクションです。テーブルセクションの場合、それは
HTMLTableSectionElement
の
行
コレクションです。)親要素が存在しない場合、この属性は−1を返す必要があります。
cells 属性は、この
HTMLCollection
を返す必要があります。
この tr 要素をルートとし、そのフィルターはこの tr 要素の子要素である td および
th 要素に一致します。
insertCell(index) メソッドは、以下のように動作する必要があります。
index が −1 より小さいか、cells コレクション内の要素の数より大きい場合、
"IndexSizeError" DOMException
をスローする必要があります。
table cell を作成する結果とし、この tr 要素の ノードドキュメント、td を使用し、
HTML 名前空間を使用して 要素を作成 します。
index が −1 または cells
コレクション内のアイテム数と等しい場合、
この tr 要素に table cell
を追加します。
それ以外の場合、この tr 要素に table cell
を
子要素として挿入し、cells コレクション内の
index 番目の td または
th 要素の直前に配置します。
table cell を返します。
deleteCell(index) メソッドは、呼び出されたときに以下のように動作する必要があります。
index が −1 より小さいか、cells
コレクション内の最後のセルのインデックスより大きい場合、または
セルがない場合、"IndexSizeError" DOMException
をスローする必要があります。
index が −1 の場合、この cells コレクション内の最後の要素を
親要素から削除するか、cells
コレクションが空の場合は何も行いません。
td 要素
すべての現在のエンジンでサポートされています。
すべての現在のエンジンでサポートされています。
tr要素の子要素として。
td要素の終了タグは、
td要素が直後に別のtdまたは
th要素に続く場合、または親要素にこれ以上コンテンツがない場合、省略することができます。
colspan — セルがまたがる列数
rowspan — セルがまたがる行数
headers — このセルのヘッダーセル
[Exposed =Window ]
interface HTMLTableCellElement : HTMLElement {
[HTMLConstructor ] constructor ();
[CEReactions ] attribute unsigned long colSpan ;
[CEReactions ] attribute unsigned long rowSpan ;
[CEReactions ] attribute DOMString headers ;
readonly attribute long cellIndex ;
[CEReactions ] attribute DOMString scope ; // th要素にのみ準拠
[CEReactions ] attribute DOMString abbr ; // th要素にのみ準拠
// 廃止されたメンバーも含まれます
};
このHTMLTableCellElementインターフェースは、
th要素にも使用されます。
td要素およびその
colspan、
rowspan、
およびheaders属性は
テーブルモデルに参加します。
ユーザーエージェントは、特に非視覚的な環境や、テーブルを2次元グリッドとして表示することが実際的でない環境において、セルの内容をレンダリングする際にセルのコンテキストをユーザーに提供する場合があります。
例えば、テーブルモデルにおけるセルの位置や、セルのヘッダーセルをリストアップするなどです(
ヘッダーセルの割り当てアルゴリズムによって決定されます)。
ヘッダーセルがリストアップされている場合、ユーザーエージェントは、ヘッダーセルそのものの内容の代わりに、それらのヘッダーセルに設定されている
abbr属性の値を使用する場合があります。
この例では、編集可能なセルのグリッド(基本的にはシンプルなスプレッドシート)から成るウェブアプリケーションのスニペットを示しています。
セルの1つは、上記のセルの合計を表示するように構成されています。3つのセルはヘッダーとしてマークされており、
それらはth要素の代わりにtd要素を使用しています。
スクリプトがこれらの要素にイベントハンドラーをアタッチして、合計を維持します。
< table >
< tr >
< th >< input value = "Name" >
< th >< input value = "Paid ($)" >
< tr >
< td >< input value = "Jeff" >
< td >< input value = "14" >
< tr >
< td >< input value = "Britta" >
< td >< input value = "9" >
< tr >
< td >< input value = "Abed" >
< td >< input value = "25" >
< tr >
< td >< input value = "Shirley" >
< td >< input value = "2" >
< tr >
< td >< input value = "Annie" >
< td >< input value = "5" >
< tr >
< td >< input value = "Troy" >
< td >< input value = "5" >
< tr >
< td >< input value = "Pierce" >
< td >< input value = "1000" >
< tr >
< th >< input value = "Total" >
< td >< output value = "1060" >
</ table >
th要素
すべての現行エンジンでサポートされています。
tr要素の子要素として。
header、
footer、
セクショニングコンテンツ、
または見出しコンテンツの子孫を含まない。
th要素の終了タグは、
th要素が直後に別のtdまたはth要素に続く場合、
または親要素にこれ以上コンテンツがない場合、省略することができます。
colspan — セルがまたがる列数
rowspan — セルがまたがる行数
headers — このセルのヘッダーセル
scope — このヘッダーセルが適用されるセルの範囲を指定
abbr — 別の文脈でセルを参照する際に使用する代替ラベル
HTMLTableCellElement
を使用し、
td要素に対して定義された通りです。
th要素には、scopeコンテンツ属性が指定されることがあります。
scope属性は、次のキーワードと状態を持つ列挙型属性です。
| キーワード | 状態 | 簡単な説明 |
|---|---|---|
row
| row | ヘッダーセルは、同じ行内のいくつかの後続のセルに適用されます。 |
col
| column | ヘッダーセルは、同じ列内のいくつかの後続のセルに適用されます。 |
rowgroup
| 行グループ | ヘッダーセルは、行グループ内の残りのすべてのセルに適用されます。 |
colgroup
| 列グループ | ヘッダーセルは、列グループ内の残りのすべてのセルに適用されます。 |
属性の欠損値デフォルトと無効値デフォルトは、 いずれも自動状態です。(この状態では、ヘッダーセルは文脈に基づいて選択されたセルのセットに適用されます。)
th要素のscope属性は、
要素が行グループに固定されていない場合、
行グループ状態にすることはできません。
また、要素が列グループに固定されていない場合、
列グループ状態にすることはできません。
th要素には、
abbrコンテンツ属性が指定されることがあります。
その値は、別の文脈でヘッダーセルを参照する際に使用される代替ラベルでなければなりません
(例:データセルに適用されるヘッダーセルを記述する場合)。通常は、フルヘッダーセルの省略形ですが、
拡張形や、単に異なる表現の場合もあります。
th要素とそのcolspan、rowspan、
headers、
およびscope属性は、
テーブルモデルに参加します。
次の例は、scope属性のrowgroup値が、ヘッダセルがどのデータセルに適用されるかにどのように影響するかを示しています。
以下は、テーブルを示すマークアップの断片です:
< table >
< thead >
< tr > < th > ID < th > Measurement < th > Average < th > Maximum
< tbody >
< tr > < td > < th scope = rowgroup > Cats < td > < td >
< tr > < td > 93 < th > Legs < td > 3.5 < td > 4
< tr > < td > 10 < th > Tails < td > 1 < td > 1
< tbody >
< tr > < td > < th scope = rowgroup > English speakers < td > < td >
< tr > < td > 32 < th > Legs < td > 2.67 < td > 4
< tr > < td > 35 < th > Tails < td > 0.33 < td > 1
</ table >
これにより、次のようなテーブルが作成されます:
| ID | Measurement | Average | Maximum |
|---|---|---|---|
| Cats | |||
| 93 | Legs | 3.5 | 4 |
| 10 | Tails | 1 | 1 |
| English speakers | |||
| 32 | Legs | 2.67 | 4 |
| 35 | Tails | 0.33 | 1 |
最初の行のヘッダはすべて、それぞれの列の行に直接適用されます。
scope属性がrowgroup状態にあるヘッダは、最初の列以外のその行グループのすべてのセルに適用されます。
残りのヘッダは、それぞれの右側のセルにのみ適用されます。
tdおよび
th
要素に共通する属性
td
および
th
要素には、colspan
コンテンツ属性を指定でき、その値は0より大きく、1000以下の
有効な非負整数
でなければなりません。
td
および
th
要素には、rowspan
コンテンツ属性も指定でき、その値は
有効な非負整数
で65534以下でなければなりません。この属性の値が0の場合、そのセルは行グループ内の残りのすべての行にまたがります。
これらの属性は、それぞれセルがまたがる列と行の数を指定します。これらの属性は、 表モデル の記述にあるように、セルを重ねるために使用してはなりません。
td
および
th
要素には、headers
コンテンツ属性を指定できます。指定されている場合、
headers
属性には、空白で区切られた一意のトークンの順序なしセット
からなる文字列を含めなければなりません。このトークンのどれも他のトークンと
同一であってはなりません。
また、各トークンの値は、
ID
の値でなければならず、そのIDは、th
要素が、td
要素または
th
要素とともに同じ
表
に属することを意味します(表モデル
に定義されている通り)。
th
要素が
ID属性を持つ場合、その
id は、同じ
表
に属し、その属性値に
ID
idが含まれている
td
要素および
th
要素により
「直接ターゲット」にされているとされます。要素
Aは、要素
th
またはtd
要素
Bにより「ターゲット」にされているとされる場合、
AがBに「直接ターゲット」されている場合、または要素
CがBによりターゲットされており、
AがCに「直接ターゲット」されている場合です。
th
要素は、それ自身を「ターゲット」としてはなりません。
colspan、
rowspan、
および
headers
属性は、表モデル
に参加します。
cell.cellIndex
セルの位置を、行のcells
リスト内で返します。これは、必ずしも表内のセルのx位置に対応しているわけではありません。前のセルが複数の行または列にまたがっている可能性があるからです。
要素が行内にない場合は、−1を返します。
colSpan
IDL属性は、colspan
コンテンツ属性を反映する必要があります。それは範囲内に制限されています[1, 1000]、およびそのデフォルト値は1です。
rowSpan
IDL属性は、rowspan
コンテンツ属性を反映する必要があります。それは範囲内に制限されています[0, 65534]、およびそのデフォルト値は1です。
headers
IDL属性は、同じ名前のコンテンツ属性を反映する必要があります。
cellIndex
IDL属性は、要素に親tr要素がある場合、親要素のcellsコレクション内のセル要素のインデックスを返します。親要素がない場合は、属性は−1を返す必要があります。
scope
IDL属性は、同じ名前のコンテンツ属性を反映する必要があります。既知の値のみに制限されます。
abbr
IDL属性は、同じ名前のコンテンツ属性を反映する必要があります。
さまざまなテーブル要素とそのコンテンツ属性は、テーブルモデルを定義します。
テーブルは、(x, y)
の座標を持つスロットの2次元グリッド上に配置されたセルで構成されます。グリッドは有限であり、空であるか、1つ以上のスロットを持っています。グリッドに1つ以上のスロットがある場合、x座標は常に0
≤ x < xwidthの範囲内にあり、y座標は常に0 ≤ y <
yheightの範囲内にあります。xwidthとyheightのいずれかまたは両方がゼロの場合、テーブルは空であり(スロットがありません)、テーブルはtable要素に対応します。
セルは、特定のwidthとheightを持ち、セルがx,
y座標のすべてのスロットをカバーするように、スロット(cellx,
celly)にアンカーされたスロットのセットです。cellx ≤ x <
cellx+widthおよびcelly ≤ y <
celly+heightの範囲で、セルはデータセルまたはヘッダーセルになることができます。データセルはtd要素に対応し、ヘッダーセルはth要素に対応します。両方のタイプのセルには、ゼロまたはそれ以上の関連ヘッダーセルがある場合があります。
エラーが発生する場合、2つのセルが同じスロットを占有することがあります。
行は、特定のy値に対してx=0からx=xwidth-1までのスロットの完全なセットです。行は通常、tr要素に対応しますが、行グループは、複数行にまたがるセルを含む場合に、一部の暗黙の行を末尾に持つことがあります。
列は、特定のx値に対してy=0からy=yheight-1までのスロットの完全なセットです。列はcol要素に対応することがありますが、col要素がない場合、列は暗黙的に存在します。
行グループは、スロット(0,
groupy)にアンカーされた行のセットであり、特定のheightを持ち、x, y座標が0 ≤
x < xwidthおよびgroupy ≤ y <
groupy+heightの範囲でカバーされる行グループです。行グループはtbody、thead、およびtfoot要素に対応します。すべての行が行グループに含まれているわけではありません。
列グループは、スロット(groupx,
0)にアンカーされた列のセットであり、特定のwidthを持ち、x, y座標がgroupx ≤
x < groupx+widthおよび0 ≤ y <
yheightの範囲でカバーされる列グループです。列グループはcolgroup要素に対応します。すべての列が列グループに含まれているわけではありません。
行グループは互いに重ならないようにします。同様に、列グループも互いに重ならないようにします。
セルは、2つ以上の行グループにまたがるスロットをカバーすることはできません。ただし、セルが複数の列グループに含まれることは可能です。1つのセルを構成するすべてのスロットは、ゼロまたは1つの行グループおよびゼロまたは複数の列グループに属しています。
テーブルには、セル、列、行、行グループ、および列グループに加えて、見出しや説明を与えるcaption要素を持つことができます。
テーブルモデルエラーとは、table要素とその子孫によって表されるデータにエラーがあることを指します。文書にはテーブルモデルエラーがあってはなりません。
table要素に関連付けられたテーブルのスロットに対応する要素を決定し、テーブルの寸法
(xwidthおよびyheight) を決定し、テーブルモデルエラーが存在するかどうかを確認するために、ユーザーエージェントは次のアルゴリズムを使用する必要があります。
xwidthをゼロに設定します。
yheightをゼロに設定します。
保留中のtfoot要素を、最初は空のリストとして設定します。
テーブルを、table要素によって表されるテーブルとします。xwidthとyheightの変数はテーブルの寸法を示します。テーブルは最初は空です。
もしtable要素に子要素がない場合、そのテーブルを返します
(空のままです)。
table要素の最初のcaption子要素をテーブルに関連付けます。該当する子要素がない場合、関連するcaption要素はありません。
現在の要素をtable要素の最初の子要素に設定します。
このアルゴリズムのステップで現在の要素をtableの次の子要素に進めることが必要であり、そのような次の子要素が存在しない場合、ユーザーエージェントはこのアルゴリズムの終わり近くにある終了ラベルが付いたステップにジャンプしなければなりません。
もし現在の要素がcolgroupの場合、以下のサブステップに従います。
コラムグループ: 現在の要素を以下の適切なケースに従って処理します。
col子要素を持っている場合
以下のステップに従います。
xstartにxwidthの値を設定します。
コラム: もし現在のコラムがcol要素であり、span属性を持っている場合、その値を負でない整数の解析ルールを使用して解析します。
もし値の解析結果がエラーやゼロでない場合、その値をspanに設定します。
それ以外の場合、col要素がspan属性を持っていない場合、または属性の値の解析がエラーやゼロになった場合は、spanを1に設定します。
もしspanが1000を超える場合、それを1000に設定します。
xwidthをspan分増加させます。
もし現在のコラムがcol要素の最後の子要素でない場合、現在のコラムをcolgroup要素の次のcol子要素に設定し、コラムラベルが付いたステップに戻ります。
xstartからxwidth-1までのテーブル内のすべての最後のコラムが、新しいコラムグループを形成し、スロット(xstart,
0)にアンカーされ、幅xwidth-xstartでcolgroup要素に対応します。
col要素を持っていない場合
もしcolgroup要素がspan属性を持っている場合、その値を負でない整数の解析ルールを使用して解析します。
もし値の解析結果がエラーやゼロでない場合、その値をspanに設定します。
それ以外の場合、colgroup要素がspan属性を持っていない場合、または属性の値の解析がエラーやゼロになった場合は、spanを1に設定します。
もしspanが1000を超える場合、それを1000に設定します。
xwidthをspan分増加させます。
テーブル内の最後のspan個のコラムが、新しいコラムグループを形成し、スロット(xwidth-span,
0)にアンカーされ、幅spanでcolgroup要素に対応します。
もし現在の要素がcolgroup要素である場合、上記のコラムグループラベルが付いたステップにジャンプします。
ycurrentをゼロに設定します。
下方に成長するセルのリストを空のリストに設定します。
もし現在の要素がtrである場合、行を処理するアルゴリズムを実行し、現在の要素をtableの次の子要素に進め、行ラベルが付いたステップに戻ります。
行グループを終了するアルゴリズムを実行します。
もし現在の要素がtfootである場合、その要素を保留中のtfoot要素のリストに追加し、現在の要素をtableの次の子要素に進め、行ラベルが付いたステップに戻ります。
行グループを処理するアルゴリズムを実行します。
行ラベルが付いたステップに戻ります。
終了: 保留中のtfoot要素のリスト内の各tfoot要素に対して、ツリー順に、行グループを処理するアルゴリズムを実行します。
もしテーブル内に、スロットのみを含む行または列が存在し、それにアンカーされたセルがない場合、これはテーブルモデルエラーです。
テーブルを返します。
行グループを処理するアルゴリズムは、thead、tbody、およびtfoot要素を処理するために上記の手順セットによって呼び出されるものです:
ystartにyheightの値を設定する。
処理されている要素の子である各tr要素について、ツリー順で行を処理するためのアルゴリズムを実行する。
もしyheightがystartより大きい場合、y=ystartからy=yheight-1までのthe table内の最後の行は、新しい行グループを形成し、(0, ystart)の座標でアンカーされ、高さはyheight-ystartで、処理されている要素に対応する。
行グループを終了するためのアルゴリズムを実行する。
行グループを終了するアルゴリズムは、上記の手順セットによって行ブロックの開始時および終了時に呼び出されます:
ycurrentがyheightより小さい間、次のステップを実行します:
下方向に成長するセルを成長させるアルゴリズムを実行します。
ycurrentを1増やします。
list of downward-growing cellsを空にします。
行を処理するアルゴリズムは、tr要素を処理するために上記の手順セットによって呼び出されます:
yheightがycurrentと等しい場合、yheightを1増やします。(ycurrentがyheightより大きくなることはありません。)
xcurrentを0に設定します。
下方向に成長するセルを成長させるアルゴリズムを実行します。
処理対象のtr要素にtdまたはth要素の子がない場合、ycurrentを1増やし、この手順セットを中止して、上記のアルゴリズムに戻ります。
Cells: xcurrentがxwidth未満であり、xcurrent、ycurrentの座標を持つスロットに既にセルが割り当てられている場合、xcurrentを1増やします。
xcurrentがxwidthと等しい場合、xwidthを1増やします。(xcurrentがxwidthより大きくなることはありません。)
もしcurrent cellがcolspan属性を持っている場合、その属性の値を解析し、その結果をcolspanとします。
その値の解析が失敗した場合、またはゼロを返した場合、あるいは属性がない場合、代わりにcolspanを1に設定します。
もしcolspanが1000を超える場合、それを1000に設定します。
もしcurrent cellがrowspan属性を持っている場合、その属性の値を解析し、その結果をrowspanとします。
その値の解析が失敗した場合、あるいは属性がない場合、代わりにrowspanを1に設定します。
もしrowspanが65534を超える場合、それを65534に設定します。
もしrowspanがゼロであり、table要素のノードドキュメントがクイークスモードに設定されていない場合、cell grows
downwardをtrueに設定し、rowspanを1に設定します。そうでない場合、cell grows
downwardをfalseに設定します。
もしxwidthがxcurrent+colspanより小さい場合、xwidthをxcurrent+colspanに設定します。
もしyheightがycurrent+rowspanより小さい場合、yheightをycurrent+rowspanに設定します。
座標(x, y)を持つスロットに、xcurrent ≤ x < xcurrent+colspanかつycurrent ≤ y < ycurrent+rowspanである場合、新しいセル cにカバーされるものとし、(xcurrent, ycurrent)に固定され、幅がcolspan、高さがrowspanであり、処理中のcurrent cell要素に対応します。
もしcurrent cell要素がth要素である場合、この新しいセルcをヘッダセルとし、それ以外の場合はデータセルとします。
現在のセル要素にどのヘッダセルが適用されるかを確立するには、次のセクションで説明されているヘッダセルを割り当てるアルゴリズムを使用します。
もし関連するスロットのいずれかに既にセルがカバーされている場合、これはテーブルモデルエラーです。これらのスロットには現在、2つのセルが重なっています。
もしcell grows downwardがtrueの場合、タプル{c, xcurrent, colspan}をlist of downward-growing cellsに追加します。
xcurrentをcolspanだけ増やします。
もしcurrent cellがtdまたはth要素の子であり、処理中のtr要素の最後のものである場合、ycurrentを1増やし、この手順セットを中止して、上記のアルゴリズムに戻ります。
Cellsとラベル付けされた手順に戻ります。
上記のアルゴリズムがユーザーエージェントに下方向に成長するセルを成長させるアルゴリズムを実行するように求める場合、ユーザーエージェントは、list of downward-growing cells内の各タプル{cell, cellx, width}に対して、セルcellをセルに拡張し、座標(x, ycurrent)をカバーするようにします。この場合、cellx ≤ x < cellx+widthとなります。
各セルにはゼロ個以上のヘッダーセルを割り当てることができます。セル主要セルにヘッダーセルを割り当てるためのアルゴリズムは次のとおりです。
ヘッダーリストを空のセルリストとして設定します。
(principalx, principaly) を主要セルがアンカーされているスロットの座標として設定します。
headers属性を指定している場合
主要セルのheaders属性の値を取得し、ASCII空白で分割して、idリストを得られたトークンのリストとして設定します。
idリストの各トークンについて、そのトークンと同じIDを持つ最初のDocument内の要素が同じテーブル内のセルであり、そのセルが主要セルでない場合、そのセルをヘッダーリストに追加します。
headers属性を指定していない場合
principalwidthを主要セルの幅として設定します。
principalheightを主要セルの高さとして設定します。
principalyからprincipaly+principalheight-1までの各yの値について、ヘッダーセルをスキャンして割り当てるための内部アルゴリズムを、主要セル、ヘッダーリスト、初期座標(principalx, y)、および増分Δx=−1とΔy=0で実行します。
principalxからprincipalx+principalwidth-1までの各xの値について、ヘッダーセルをスキャンして割り当てるための内部アルゴリズムを、主要セル、ヘッダーリスト、初期座標(x, principaly)、および増分Δx=0とΔy=−1で実行します。
もし主要セルが行グループにアンカーされている場合、同じ行グループにアンカーされ、かつprincipalx+principalwidth-1以下のx座標およびprincipaly+principalheight-1以下のy座標を持つすべての行グループヘッダーをヘッダーリストに追加します。
もし主要セルが列グループにアンカーされている場合、同じ列グループにアンカーされ、かつprincipalx+principalwidth-1以下のx座標およびprincipaly+principalheight-1以下のy座標を持つすべての列グループヘッダーをヘッダーリストに追加します。
ヘッダーリストからすべての空セルを削除します。
ヘッダーリストから重複を削除します。
もし主要セルがヘッダーリストに存在する場合、それを削除します。
ヘッダーリストのヘッダーを主要セルに割り当てます。
主要セル、ヘッダーリスト、初期座標(initialx, initialy)、およびΔxとΔyの増分が与えられた場合のヘッダーセルをスキャンして割り当てるための内部アルゴリズムは次のとおりです。
xをinitialxと等しく設定します。
yをinitialyと等しく設定します。
不透明ヘッダーを空のセルリストとして設定します。
ヘッダーブロック内をtrueに設定し、現在のヘッダーブロックからのヘッダーを主要セルのみを含むセルリストとして設定します。
ヘッダーブロック内をfalseに設定し、現在のヘッダーブロックからのヘッダーを空のセルリストとして設定します。
ループ: Δxを用いてxを増加させ、Δyを用いてyを増加させます。
このアルゴリズムの各呼び出しにおいて、ΔxとΔyのいずれかは-1であり、もう一方は0になります。
もしxまたはyが0未満の場合、この内部アルゴリズムを中止します。
もしスロット(x, y)をカバーするセルが存在しない場合、またはスロット(x, y)をカバーするセルが複数存在する場合、ループラベルが付いたサブステップに戻ります。
現在のセルをスロット(x, y)をカバーするセルとして設定します。
ヘッダーブロック内をtrueに設定します。
現在のセルを現在のヘッダーブロックからのヘッダーに追加します。
ブロックされたをfalseに設定します。
もしブロックされたがfalseである場合、現在のセルをヘッダーリストに追加します。
ヘッダーブロック内をfalseに設定します。現在のヘッダーブロックからのヘッダー内のすべてのセルを不透明ヘッダーリストに追加し、現在のヘッダーブロックからのヘッダーリストを空にします。
ループラベルが付いたステップに戻ります。
座標(x, y)にアンカーされ、幅width、高さheightを持つヘッダーセルは、次のいずれかが真である場合、コラムヘッダーであると見なされます。
座標(x, y)にアンカーされ、幅width、高さheightを持つヘッダーセルは、次のいずれかが真である場合、行ヘッダーであると見なされます。
ヘッダーセルは、そのscope属性がコラムグループ状態にある場合、コラムグループヘッダーであると見なされます。
ヘッダーセルは、そのscope属性が行グループ状態にある場合、行グループヘッダーであると見なされます。
セルは、それが要素を含まず、またはその子テキストコンテンツ(もしあれば)がASCII空白のみで構成されている場合、空セルであると見なされます。
このセクションは規範的ではありません。
以下は、Smithsonian physical tables, Volume 71の表45の下部をどのようにマークアップするかを示したものです:
< table >
< caption > 仕様値: < b > 鋼</ b > , < b > 鋳物</ b > , Ann. A.S.T.M. A27-16, クラスB;* P最大0.06; S最大0.05.</ caption >
< thead >
< tr >
< th rowspan = 2 > グレード.</ th >
< th rowspan = 2 > 降伏点.</ th >
< th colspan = 2 > 引張強度</ th >
< th rowspan = 2 > 伸び率 50.8 mm または 2 インチ.</ th >
< th rowspan = 2 > 断面収縮率.</ th >
</ tr >
< tr >
< th > kg/mm< sup > 2</ sup ></ th >
< th > lb/in< sup > 2</ sup ></ th >
</ tr >
</ thead >
< tbody >
< tr >
< td > 硬</ td >
< td > 0.45 極限</ td >
< td > 56.2</ td >
< td > 80,000</ td >
< td > 15</ td >
< td > 20</ td >
</ tr >
< tr >
< td > 中</ td >
< td > 0.45 極限</ td >
< td > 49.2</ td >
< td > 70,000</ td >
< td > 18</ td >
< td > 25</ td >
</ tr >
< tr >
< td > 軟</ td >
< td > 0.45 極限</ td >
< td > 42.2</ td >
< td > 60,000</ td >
< td > 22</ td >
< td > 30</ td >
</ tr >
</ tbody >
</ table >
この表は次のように表示される可能性があります:
| グレード. | 降伏点. | 引張強度 | 伸び率 50.8 mm または 2 in. | 断面収縮率. | |
|---|---|---|---|---|---|
| kg/mm2 | lb/in2 | ||||
| 硬 | 0.45 極限 | 56.2 | 80,000 | 15 | 20 |
| 中 | 0.45 極限 | 49.2 | 70,000 | 18 | 25 |
| 軟 | 0.45 極限 | 42.2 | 60,000 | 22 | 30 |
以下は、Apple, Incの2008会計年度の10-K報告書の46ページにある粗利益表をどのようにマークアップするかを示したものです:
< table >
< thead >
< tr >
< th >
< th > 2008
< th > 2007
< th > 2006
</ tr >
</ thead >
< tbody >
< tr >
< th > 売上高
< td > $ 32,479
< td > $ 24,006
< td > $ 19,315
</ tr >
< tr >
< th > 売上原価
< td > 21,334
< td > 15,852
< td > 13,717
</ tr >
< tr >
< th > 粗利益
< td > $ 11,145
< td > $ 8,154
< td > $ 5,598
</ tr >
</ tbody >
</ tfoot >
< tr >
< th > 粗利益率
< td > 34.3%
< td > 34.0%
< td > 29.0%
</ table >
この表は次のように表示される可能性があります:
| 2008 | 2007 | 2006 | |
|---|---|---|---|
| 売上高 | $ 32,479 | $ 24,006 | $ 19,315 |
| 売上原価 | 21,334 | 15,852 | 13,717 |
| 粗利益 | $ 11,145 | $ 8,154 | $ 5,598 |
| 粗利益率 | 34.3% | 34.0% | 29.0% |
以下は、同じ文書の下部にある営業費用表をどのようにマークアップするかを示したものです:
< table >
< colgroup > < col >
< colgroup > < col > < col > < col >
< thead >
< tr > < th > < th > 2008 < th > 2007 < th > 2006
< tbody >
< tr > < th scope = rowgroup > Research and development
< td > $ 1,109 < td > $ 782 < td > $ 712
< tr > < th scope = row > Percentage of net sales
< td > 3.4% < td > 3.3% < td > 3.7%
< tbody >
< tr > < th scope = rowgroup > Selling, general, and administrative
< td > $ 3,761 < td > $ 2,963 < td > $ 2,433
< tr > < th scope = row > Percentage of net sales
< td > 11.6% < td > 12.3% < td > 12.6%
</ table >
この表は次のように表示される可能性があります:
| 2008 | 2007 | 2006 | |
|---|---|---|---|
| 研究開発 | $ 1,109 | $ 782 | $ 712 |
| 売上高に対する割合 | 3.4% | 3.3% | 3.7% |
| 販売費および一般管理費 | $ 3,761 | $ 2,963 | $ 2,433 |
| 売上高に対する割合 | 11.6% | 12.3% | 12.6% |
すべての現行エンジンでサポートされています。
このセクションは規範的ではありません。
フォームは、テキスト、ボタン、チェックボックス、範囲、またはカラーピッカーコントロールなどのフォームコントロールを持つWebページのコンポーネントです。ユーザーはこのようなフォームと対話し、データを提供し、それをサーバーに送信してさらなる処理を行うことができます(例:検索結果や計算結果の返送)。多くの場合、クライアントサイドスクリプトは必要ありませんが、スクリプトがユーザーエクスペリエンスを拡張したり、データをサーバーに送信する以外の目的でフォームを使用するためのAPIが利用可能です。
フォームの作成は、ユーザーインターフェースの記述、サーバー側処理の実装、ユーザーインターフェースをサーバーと通信させる設定など、任意の順序で実行できるいくつかのステップで構成されます。
このセクションは規範的ではありません。
この簡単な紹介の目的のために、ピザ注文フォームを作成します。
どのフォームも、form
要素から始まり、その中にコントロールが配置されます。ほとんどの
コントロールは、input
要素で表され、デフォルトではテキスト
コントロールを提供します。コントロールにラベルを付けるには、label
要素が使用され、ラベルのテキストと
コントロール自体は、label
要素内に配置されます。フォームの各部分は
段落と見なされ、通常は他の部分と区別するためにp
要素を使用して区切られます。
これをまとめると、顧客の名前を尋ねる方法は次のようになります:
< form >
< p >< label > Customer name: < input ></ label ></ p >
</ form >
ユーザーがピザのサイズを選択できるように、ラジオボタンのセットを使用できます。ラジオボタンもinput
要素を使用し、今回はtype
属性を持つ
値 radioを使用します。
ラジオボタンをグループとして機能させるために、name属性を使用して共通の名前を付けます。
一連の
コントロールをグループ化するには、たとえばこの場合、ラジオボタンなどのfieldset
要素を使用します。そのようなコントロールのグループのタイトルは、fieldset
の最初の要素であるlegend
要素によって指定されます。
< form >
< p >< label > Customer name: < input ></ label ></ p >
< fieldset >
< legend > ピザサイズ </ legend >
< p >< label > < input type = radio name = size > Small </ label ></ p >
< p >< label > < input type = radio name = size > Medium </ label ></ p >
< p >< label > < input type = radio name = size > Large </ label ></ p >
</ fieldset >
</ form >
前のステップからの変更点が強調表示されています。
トッピングを選択するには、チェックボックスを使用できます。これらはinput
要素
とtype
属性がチェックボックスに設定されている値 checkboxを使用します。
< form >
< p >< label > Customer name: < input ></ label ></ p >
< fieldset >
< legend > ピザサイズ </ legend >
< p >< label > < input type = radio name = size > Small </ label ></ p >
< p >< label > < input type = radio name = size > Medium </ label ></ p >
< p >< label > < input type = radio name = size > Large </ label ></ p >
</ fieldset >
< fieldset >
< legend > ピザトッピング </ legend >
< p >< label > < input type = checkbox > Bacon </ label ></ p >
< p >< label > < input type = checkbox > Extra Cheese </ label ></ p >
< p >< label > < input type = checkbox > Onion </ label ></ p >
< p >< label > < input type = checkbox > Mushroom </ label ></ p >
</ fieldset >
</ form >
このフォームが作成されているピッツェリアは常にミスを犯すため、顧客と連絡を取る方法が必要です。この目的のために、電話番号(input
要素とそのtype
属性をtelに設定)
および電子メールアドレス
(input
要素とそのtype
属性が
emailに設定されています)を使用できます:
< form >
< p >< label > Customer name: < input ></ label ></ p >
< p >< label > Telephone: < input type = tel ></ label ></ p >
< p >< label > Email address: < input type = email ></ label ></ p >
< fieldset >
< legend > Pizza Size </ legend >
< p >< label > < input type = radio name = size > Small </ label ></ p >
< p >< label > < input type = radio name = size > Medium </ label ></ p >
< p >< label > < input type = radio name = size > Large </ label ></ p >
</ fieldset >
< fieldset >
< legend > Pizza Toppings </ legend >
< p >< label > < input type = checkbox > Bacon </ label ></ p >
< p >< label > < input type = checkbox > Extra Cheese </ label ></ p >
< p >< label > < input type = checkbox > Onion </ label ></ p >
< p >< label > < input type = checkbox > Mushroom </ label ></ p >
</ fieldset >
</ form >
配達時間を尋ねるために、input
要素
とそのtype
属性をtime
に設定して使用できます。多くの
これらのフォームコントロールには、指定できる値を正確に制御する属性があります。この場合、特に関心のある属性は、min、max、および
stepです。
これらは、最小時間、最大時間、および許可される値間の間隔(秒)を設定します。この
ピッツェリアは午前11時から午後9時までしか配達せず、15分以上の間隔を保証していませんが、次のようにマークアップできます:
< form >
< p >< label > Customer name: < input ></ label ></ p >
< p >< label > Telephone: < input type = tel ></ label ></ p >
< p >< label > Email address: < input type = email ></ label ></ p >
< fieldset >
< legend > Pizza Size </ legend >
< p >< label > < input type = radio name = size > Small </ label ></ p >
< p >< label > < input type = radio name = size > Medium </ label ></ p >
< p >< label > < input type = radio name = size > Large </ label ></ p >
</ fieldset >
< fieldset >
< legend > Pizza Toppings </ legend >
< p >< label > < input type = checkbox > Bacon </ label ></ p >
< p >< label > < input type = checkbox > Extra Cheese </ label ></ p >
< p >< label > < input type = checkbox > Onion </ label ></ p >
< p >< label > < input type = checkbox > Mushroom </ label ></ p >
</ fieldset >
< p >< label > Preferred delivery time: < input type = time min = "11:00" max = "21:00" step = "900" ></ label ></ p >
</ form >
textarea
要素は、複数行のテキストコントロールを提供するために使用できます。この
場合、顧客に配達指示を提供するスペースを提供します:
< form >
< p >< label > Customer name: < input ></ label ></ p >
< p >< label > Telephone: < input type = tel ></ label ></ p >
< p >< label > Email address: < input type = email ></ label ></ p >
< fieldset >
< legend > Pizza Size </ legend >
< p >< label > < input type = radio name = size > Small </ label ></ p >
< p >< label > < input type = radio name = size > Medium </ label ></ p >
< p >< label > < input type = radio name = size > Large </ label ></ p >
</ fieldset >
< fieldset >
< legend > Pizza Toppings </ legend >
< p >< label > < input type = checkbox > Bacon </ label ></ p >
< p >< label > < input type = checkbox > Extra Cheese </ label ></ p >
< p >< label > < input type = checkbox > Onion </ label ></ p >
< p >< label > < input type = checkbox > Mushroom </ label ></ p >
</ fieldset >
< p >< label > Preferred delivery time: < input type = time min = "11:00" max = "21:00" step = "900" ></ label ></ p >
< p >< label > Delivery instructions: < textarea ></ textarea ></ label ></ p >
</ form >
最後に、フォームを送信可能にするために、button
要素を使用します:
< form >
< p >< label > Customer name: < input ></ label ></ p >
< p >< label > Telephone: < input type = tel ></ label ></ p >
< p >< label > Email address: < input type = email ></ label ></ p >
< fieldset >
< legend > Pizza Size </ legend >
< p >< label > < input type = radio name = size > Small </ label ></ p >
< p >< label > < input type = radio name = size > Medium </ label ></ p >
< p >< label > < input type = radio name = size > Large </ label ></ p >
</ fieldset >
< fieldset >
< legend > Pizza Toppings </ legend >
< p >< label > < input type = checkbox > Bacon </ label ></ p >
< p >< label > < input type = checkbox > Extra Cheese </ label ></ p >
< p >< label > < input type = checkbox > Onion </ label ></ p >
< p >< label > < input type = checkbox > Mushroom </ label ></ p >
</ fieldset >
< p >< label > Preferred delivery time: < input type = time min = "11:00" max = "21:00" step = "900" ></ label ></ p >
< p >< label > Delivery instructions: < textarea ></ textarea ></ label ></ p >
< p >< button > Submit order</ button ></ p >
</ form >
このセクションは規範的ではありません。
サーバーサイドプロセッサを作成するための正確な詳細は、この仕様の範囲外です。
この紹介の目的のために、https://pizza.example.com/order.cgi にあるスクリプトが、
application/x-www-form-urlencoded
形式を使用して送信を受け入れるように構成されており、
以下のパラメータがHTTP POST本文に送信されることを前提とします:
custname
custtel
custemail
size
small、medium、large のいずれか
topping
bacon、
cheese、onion、およびmushroom
delivery
comments
このセクションは規範的ではありません。
フォームの送信は、サーバーに対してさまざまな方法で公開されますが、最も一般的なのはHTTP GETまたはPOSTリクエストです。使用する正確な方法を指定するには、method
属性をform
要素に指定します。ただし、これではフォームデータがどのようにエンコードされるかは指定されません。エンコードを指定するには、enctype
属性を使用します。また、送信されたデータを処理するサービスのURLを指定する必要があり、これはaction
属性を使用して指定します。
送信する各フォームコントロールには、送信データを参照するために使用される名前を指定する必要があります。ラジオボタンのグループには既に名前を指定しました。同じ属性(name)
も送信名を指定します。
ラジオボタンは、value
属性を使用して、それぞれ異なる値を指定することで、送信時に区別されます。
複数のコントロールに同じ名前を指定することができます。たとえば、ここではすべてのチェックボックスに同じ名前を指定し、サーバーはその名前で送信された値を確認して、どのチェックボックスが選択されたかを区別します。ラジオボタンと同様に、value
属性で一意の値を指定します。
前のセクションで設定した内容を考慮すると、すべては次のようになります:
< form method = "post"
enctype = "application/x-www-form-urlencoded"
action = "https://pizza.example.com/order.cgi" >
< p >< label > Customer name: < input name = "custname" ></ label ></ p >
< p >< label > Telephone: < input type = tel name = "custtel" ></ label ></ p >
< p >< label > Email address: < input type = email name = "custemail" ></ label ></ p >
< fieldset >
< legend > Pizza Size </ legend >
< p >< label > < input type = radio name = size value = "small" > Small </ label ></ p >
< p >< label > < input type = radio name = size value = "medium" > Medium </ label ></ p >
< p >< label > < input type = radio name = size value = "large" > Large </ label ></ p >
</ fieldset >
< fieldset >
< legend > Pizza Toppings </ legend >
< p >< label > < input type = checkbox name = "topping" value = "bacon" > Bacon </ label ></ p >
< p >< label > < input type = checkbox name = "topping" value = "cheese" > Extra Cheese </ label ></ p >
< p >< label > < input type = checkbox name = "topping" value = "onion" > Onion </ label ></ p >
< p >< label > < input type = checkbox name = "topping" value = "mushroom" > Mushroom </ label ></ p >
</ fieldset >
< p >< label > Preferred delivery time: < input type = time min = "11:00" max = "21:00" step = "900" name = "delivery" ></ label ></ p >
< p >< label > Delivery instructions: < textarea name = "comments" ></ textarea ></ label ></ p >
< p >< button > Submit order</ button ></ p >
</ form >
一部の属性が値を引用符で囲んでいる理由とそうでない理由に特別な意味はありません。HTMLの構文では、属性を指定するためのさまざまな有効な方法が許可されています。この点については、構文セクションで説明されています。
たとえば、顧客が「Denise Lawrence」と名前を入力し、「555-321-8642」と電話番号を入力し、メールアドレスを指定せず、ミディアムサイズのピザを注文し、トッピングにExtra CheeseとMushroomを選び、配達時間を午後7時に指定し、配達指示テキストコントロールを空白のままにした場合、ユーザーエージェントは次の内容をオンラインウェブサービスに送信します:
custname=Denise+Lawrence&custtel=555-321-8642&custemail=&size=medium&topping=cheese&topping=mushroom&delivery=19%3A00&comments=
すべての現行エンジンでサポートされています。
このセクションは規範的ではありません。
フォームは、ユーザーエージェントがフォームを送信する前にユーザーの入力を確認するように注釈を付けることができます。サーバーは依然として入力が有効であることを確認する必要があります(悪意のあるユーザーは簡単にフォーム検証をバイパスできるため)が、サーバーが唯一の検査者であることによる待機時間を避けることができます。
最も簡単な注釈はrequired
属性であり、input
要素に指定すると、値が入力されるまでフォームを送信しないことを示します。この属性を顧客名、ピザサイズ、および配達時間のフィールドに追加することで、これらのフィールドが入力されていない場合にユーザーエージェントがユーザーに通知できるようにします。
< form method = "post"
enctype = "application/x-www-form-urlencoded"
action = "https://pizza.example.com/order.cgi" >
< p >< label > Customer name: < input name = "custname" required ></ label ></ p >
< p >< label > Telephone: < input type = tel name = "custtel" ></ label ></ p >
< p >< label > Email address: < input type = email name = "custemail" ></ label ></ p >
< fieldset >
< legend > ピザサイズ </ legend >
< p >< label > < input type = radio name = size required value = "small" > Small </ label ></ p >
< p >< label > < input type = radio name = size required value = "medium" > Medium </ label ></ p >
< p >< label > < input type = radio name = size required value = "large" > Large </ label ></ p >
</ fieldset >
< fieldset >
< legend > ピザトッピング </ legend >
< p >< label > < input type = checkbox name = "topping" value = "bacon" > Bacon </ label ></ p >
< p >< label > < input type = checkbox name = "topping" value = "cheese" > Extra Cheese </ label ></ p >
< p >< label > < input type = checkbox name = "topping" value = "onion" > Onion </ label ></ p >
< p >< label > < input type = checkbox name = "topping" value = "mushroom" > Mushroom </ label ></ p >
</ fieldset >
< p >< label > Preferred delivery time: < input type = time min = "11:00" max = "21:00" step = "900" name = "delivery" required ></ label ></ p >
< p >< label > Delivery instructions: < textarea name = "comments" maxlength = 1000 ></ textarea ></ label ></ p >
< p >< button > Submit order</ button ></ p >
</ form >
フォームが送信されると、invalid
イベントが無効な各フォームコントロールで発生します。これは、フォームの問題点の概要を表示するのに役立ちます。通常、ブラウザ自体は一度に1つの問題しか報告しないためです。
このセクションは規範的ではありません。
一部のブラウザは、ユーザーが情報を再入力する手間を省くために、フォームコントロールを自動的に入力しようとします。例えば、ユーザーの電話番号を要求するフィールドにユーザーの電話番号が自動的に入力されることがあります。
ユーザーエージェントを支援するために、autocomplete属性を使用してフィールドの目的を説明できます。このフォームの場合、ピザの配達先に関する情報をこのように注釈を付けることが有用です。この情報を追加すると、次のようになります。
< form method = "post"
enctype = "application/x-www-form-urlencoded"
action = "https://pizza.example.com/order.cgi" >
< p >< label > 顧客名: < input name = "custname" required autocomplete = "shipping name" ></ label ></ p >
< p >< label > 電話番号: < input type = tel name = "custtel" autocomplete = "shipping tel" ></ label ></ p >
< p >< label > メールアドレス: < input type = email name = "custemail" autocomplete = "shipping email" ></ label ></ p >
< fieldset >
< legend > ピザのサイズ </ legend >
< p >< label > < input type = radio name = size required value = "small" > 小 </ label ></ p >
< p >< label > < input type = radio name = size required value = "medium" > 中 </ label ></ p >
< p >< label > < input type = radio name = size required value = "large" > 大 </ label ></ p >
</ fieldset >
< fieldset >
< legend > ピザのトッピング </ legend >
< p >< label > < input type = checkbox name = "topping" value = "bacon" > ベーコン </ label ></ p >
< p >< label > < input type = checkbox name = "topping" value = "cheese" > 追加チーズ </ label ></ p >
< p >< label > < input type = checkbox name = "topping" value = "onion" > 玉ねぎ </ label ></ p >
< p >< label > < input type = checkbox name = "topping" value = "mushroom" > マッシュルーム </ label ></ p >
</ fieldset >
< p >< label > 配達希望時間: < input type = time min = "11:00" max = "21:00" step = "900" name = "delivery" required ></ label ></ p >
< p >< label > 配達指示: < textarea name = "comments" maxlength = 1000 ></ textarea ></ label ></ p >
< p >< button > 注文を送信</ button ></ p >
</ form >
このセクションは規範的ではありません。
一部のデバイス、特に仮想キーボードを使用するデバイスでは、ユーザーに複数の入力モードを提供することができます。例えば、クレジットカード番号を入力する際には0から9の数字キーのみを表示させたり、名前を入力する際には各単語が自動的に大文字で始まるようにすることができます。
inputmode
属性を使用することで、適切な入力モードを選択できます:
< form method = "post"
enctype = "application/x-www-form-urlencoded"
action = "https://pizza.example.com/order.cgi" >
< p >< label > Customer name: < input name = "custname" required autocomplete = "shipping name" ></ label ></ p >
< p >< label > Telephone: < input type = tel name = "custtel" autocomplete = "shipping tel" ></ label ></ p >
< p >< label > Buzzer code: < input name = "custbuzz" inputmode = "numeric" ></ label ></ p >
< p >< label > Email address: < input type = email name = "custemail" autocomplete = "shipping email" ></ label ></ p >
< fieldset >
< legend > Pizza Size </ legend >
< p >< label > < input type = radio name = size required value = "small" > Small </ label ></ p >
< p >< label > < input type = radio name = size required value = "medium" > Medium </ label ></ p >
< p >< label > < input type = radio name = size required value = "large" > Large </ label ></ p >
</ fieldset >
< fieldset >
< legend > Pizza Toppings </ legend >
< p >< label > < input type = checkbox name = "topping" value = "bacon" > Bacon </ label ></ p >
< p >< label > < input type = checkbox name = "topping" value = "cheese" > Extra Cheese </ label ></ p >
< p >< label > < input type = checkbox name = "topping" value = "onion" > Onion </ label ></ p >
< p >< label > < input type = checkbox name = "topping" value = "mushroom" > Mushroom </ label ></ p >
</ fieldset >
< p >< label > Preferred delivery time: < input type = time min = "11:00" max = "21:00" step = "900" name = "delivery" required ></ label ></ p >
< p >< label > Delivery instructions: < textarea name = "comments" maxlength = 1000 ></ textarea ></ label ></ p >
< p >< button > Submit order</ button ></ p >
</ form >
このセクションは規範的ではありません。
type、autocomplete、およびinputmode属性は、混同しやすい場合があります。たとえば、これらの属性のすべてにおいて「email」という文字列は有効な値です。このセクションでは、これら3つの属性の違いを示し、それらを使用する際のアドバイスを提供します。
type属性は、input要素で使用されるコントロールの種類を決定します。この属性の値を選択することは、input要素、textarea要素、select要素などを使用するかどうかを選択することと同じです。
対照的に、autocomplete属性は、ユーザーが入力する値が実際に何を表しているかを説明します。この属性の値を選択することは、要素のラベルを選択することと同じです。
まず、電話番号について考えてみましょう。ページがユーザーに電話番号を尋ねる場合、適切なフォームコントロールは<input type=tel>です。しかし、どのautocompleteの値を使用するかは、そのページがどの電話番号を尋ねているのか、国際フォーマットの電話番号を期待しているのか、ローカルフォーマットの電話番号を期待しているのか、などによって異なります。
たとえば、eコマースサイトのチェックアウトプロセスの一環として、顧客が友人に贈り物を購入して配送する場合、購入者の電話番号(支払いの問題が発生した場合のため)と友人の電話番号(配送の問題が発生した場合のため)の両方が必要になるかもしれません。サイトが国際電話番号(国コード付き)を期待している場合、これらは次のように見えるかもしれません:
< p >< label > Your phone number: < input type = tel name = custtel autocomplete = "billing tel" ></ label >
< p >< label > Recipient's phone number: < input type = tel name = shiptel autocomplete = "shipping tel" ></ label >
< p > Please enter complete phone numbers including the country code prefix, as in "+1 555 123 4567".
しかし、サイトがイギリスの顧客と受取人のみをサポートしている場合、次のように見えるかもしれません(tel-nationalを使用している点に注目してください。これは、telとは異なります):
< p >< label > Your phone number: < input type = tel name = custtel autocomplete = "billing tel-national" ></ label >
< p >< label > Recipient's phone number: < input type = tel name = shiptel autocomplete = "shipping tel-national" ></ label >
< p > Please enter complete UK phone numbers, as in "(01632) 960 123".
次に、個人の好みの言語を考えてみましょう。適切なautocomplete値はlanguageです。しかし、目的に応じて使用するフォームコントロールには、テキストコントロール(<input type=text>)、ドロップダウンリスト(<select>)、ラジオボタン(<input type=radio>)など、さまざまなものがあります。これらはすべて、どのようなインターフェースが望ましいかによります。
最後に、名前を考えてみましょう。ページがユーザーから名前を一つだけ求めている場合、関連するコントロールは<input type=text>です。ページがユーザーのフルネームを求めている場合、適切なautocomplete値はnameです。
< p >< label > Japanese name: < input name = "j" type = "text" autocomplete = "section-jp name" ></ label >
< label > Romanized name: < input name = "e" type = "text" autocomplete = "section-en name" ></ label >
この例では、section-*キーワードがautocomplete属性の値に含まれています。これにより、ユーザーエージェントは二つのフィールドが異なる名前を期待していることを理解します。これがない場合、ユーザーが最初のフィールドに値を入力した際に、二番目のフィールドにも同じ値が自動的に入力されてしまう可能性があります。
-jpと-enという部分は、ユーザーエージェントには不透明であり、それだけではそれぞれの名前が日本語と英語であることを推測することはできません。
typeやautocompleteの選択とは別に、inputmode属性は、テキストコントロールの場合、どのような入力方式(例えば、仮想キーボード)を使用するかを決定します。
クレジットカード番号を考えてみましょう。適切な入力タイプはではありません。<input type=number>、以下で説明されているようにです。代わりに<input type=text>を使用します。それでもユーザーエージェントに数値入力モダリティ(例えば、数字だけが表示される仮想キーボード)を使用させたい場合、ページには次のような手段を使用します。
< p >< label > Credit card number:
< input name = "cc" type = "text" inputmode = "numeric" pattern = "[0-9]{8,19}" autocomplete = "cc-number" >
</ label ></ p >
このセクションは規範的ではありません。
このピザ配達の例では、時間は「HH:MM」形式で指定されています。つまり、24時間制の2桁の時間と、2桁の分です。(秒を指定することも可能ですが、この例では必要ありません。)
しかし、いくつかの地域では、ユーザーに提示される際に時間の表現が異なることがあります。例えば、アメリカでは依然として「2pm」のように、午前/午後の表示を伴う12時間制が一般的です。フランスでは、時間と分を「14h00」のように「h」文字で区切るのが一般的です。
日付にも同様の問題があり、さらに複雑なことに、コンポーネントの順序が必ずしも一貫していない場合があります。例えば、キプロスでは2003年2月1日は通常「1/2/03」と書かれますが、日本では同じ日付が通常「2003年02月01日」と書かれます。数値に関しても、例えば小数点や千位の区切りに使用される句読点が地域によって異なるなどの違いがあります。
したがって、HTMLおよびフォーム送信で使用される時刻、日付、数値の形式(常にこの仕様で定義された形式であり、コンピュータが読み取り可能な日付と時刻の形式に関するISO 8601標準に基づく)と、ブラウザがユーザーに提示し、ユーザーから入力として受け取る際に使用される時刻、日付、数値の形式を区別することが重要です。
「オンザワイヤー」、つまりHTMLマークアップおよびフォーム送信で使用される形式は、ユーザーの地域設定に関係なく、一貫してコンピュータが読み取り可能であることを意図しています。例えば、日付は常に「YYYY-MM-DD」形式で書かれます。「2003-02-01」のようにです。一部のユーザーはこの形式を目にするかもしれませんが、他のユーザーは「01.02.2003」や「2003年2月1日」のように表示されることがあります。
ワイヤー形式でページに与えられた時刻、日付、または数値は、ユーザーの好みに基づいて(またはページ自体の地域設定に基づいて)、ユーザーに表示される前にユーザーの好みに合わせた形式に変換されます。同様に、ユーザーが好みの形式で時刻、日付、または数値を入力した後、ユーザーエージェントはそれをワイヤー形式に変換してからDOMに配置するか、送信します。
これにより、ページやサーバー上のスクリプトが、多様な形式に対応することなく、一貫した方法で時刻、日付、および数値を処理できるようになりながらも、ユーザーのニーズをサポートすることができます。
フォームコントロールのローカライズに関する実装ノートも参照してください。
主に歴史的な理由から、このセクションの要素は、フローコンテンツ、フレージングコンテンツ、インタラクティブコンテンツのような通常のカテゴリに加えて、いくつかの重複する(ただし微妙に異なる)カテゴリに分類されています。
いくつかの要素はフォーム関連要素に分類され、これらはフォームオーナーを持つことができます。
フォーム関連要素は、いくつかのサブカテゴリに分類されます:
これらは、form.elementsおよびfieldset.elementsAPIにリストされる要素を示します。これらの要素には、formコンテンツ属性と、それに対応するformIDL属性があり、作成者が明示的にフォームオーナーを指定できるようにします。
これらは、form要素が送信された際に、エントリリストを構築するために使用できる要素を示します。
いくつかの送信可能な要素は、その属性に応じてボタンとなる場合があります。以下の説明は、要素がボタンである場合を定義します。いくつかのボタンは特に送信ボタンです。
これらは、フォームオーナーからautocapitalize属性を継承する要素を示します。
いくつかの要素は、すべてがフォーム関連要素であるわけではありませんが、ラベル可能な要素として分類されています。これらはlabel要素と関連付けることができる要素です。
form要素すべての最新エンジンでサポートされています。
すべての最新エンジンでサポートされています。
form要素の子孫は含まない。accept-charset
— フォーム送信に使用する文字エンコーディング
action — URL を使用して
フォーム送信
autocomplete —
フォーム内のコントロールの自動入力機能のデフォルト設定
enctype — エントリリストのエンコード形式をフォーム送信で使用
method — フォーム送信に使用するバリアント
name — document.formsAPI内でフォームの名前を使用
novalidate — フォーム送信時にフォームコントロールの検証をバイパス
target — ナビゲータブル をフォーム送信に使用
rel
[Exposed =Window ,
LegacyOverrideBuiltIns ,
LegacyUnenumerableNamedProperties ]
interface HTMLFormElement : HTMLElement {
[HTMLConstructor ] constructor ();
[CEReactions ] attribute DOMString acceptCharset ;
[CEReactions ] attribute USVString action ;
[CEReactions ] attribute DOMString autocomplete ;
[CEReactions ] attribute DOMString enctype ;
[CEReactions ] attribute DOMString encoding ;
[CEReactions ] attribute DOMString method ;
[CEReactions ] attribute DOMString name ;
[CEReactions ] attribute boolean noValidate ;
[CEReactions ] attribute DOMString target ;
[CEReactions ] attribute DOMString rel ;
[SameObject , PutForwards =value ] readonly attribute DOMTokenList relList ;
[SameObject ] readonly attribute HTMLFormControlsCollection elements ;
readonly attribute unsigned long length ;
getter Element (unsigned long index );
getter (RadioNodeList or Element ) (DOMString name );
undefined submit ();
undefined requestSubmit (optional HTMLElement ? submitter = null );
[CEReactions ] undefined reset ();
boolean checkValidity ();
boolean reportValidity ();
};
form要素は表します、ハイパーリンクを。
これらはフォーム関連要素のコレクションを介して操作可能です。一部はサーバーで処理するために送信できる編集可能な値を表すことができます。
accept-charset属性は、送信に使用する文字エンコーディングを指定します。指定された場合、値は「UTF-8」とASCII 大文字小文字を区別しないマッチでなければなりません。[ENCODING]
name属性は、formの名前をformsコレクション内で表します。値は空文字列であってはならず、同じコレクション内の他のform要素と一意でなければなりません。
autocomplete属性は列挙属性であり、以下のキーワードと状態を持ちます:
| キーワード | 状態 | 簡単な説明 |
|---|---|---|
on
| on | フォームコントロールはデフォルトで「on」に設定されます。
|
off
| off | フォームコントロールはデフォルトで「off」に設定されます。
|
この属性の欠落値デフォルトおよび無効値デフォルトはどちらもon状態です。
action、enctype、method、novalidate、およびtarget属性はフォーム送信のための属性です。
rel属性は、form要素が作成するリンクの種類を制御します。属性の値は順不同の一意なスペース区切りトークンのセットでなければなりません。許可されたキーワードとその意味は前のセクションで定義されています。
relのサポートされているトークンは、ユーザーエージェントによって処理モデルが実装されている限り、form要素で許可されているHTMLリンクタイプで定義されたキーワードです。可能なサポートされているトークンには、noreferrer、noopener、およびopenerが含まれます。relのサポートされているトークンには、このリストからユーザーエージェントが処理モデルを実装しているトークンのみが含まれなければなりません。
form.elements
すべての最新エンジンでサポートされています。
フォーム内のフォームコントロール(歴史的な理由で画像ボタンを除く)のHTMLFormControlsCollectionを返します。
form.length
すべての最新エンジンでサポートされています。
フォーム内のフォームコントロールの数を返します(歴史的な理由で画像ボタンを除く)。
form[index]
フォーム内のindex番目の要素を返します(歴史的な理由で画像ボタンを除く)。
form[name]
指定されたIDまたはnameを持つフォーム内のフォームコントロール(または複数ある場合はRadioNodeList)を返します(歴史的な理由で画像ボタンを除く)。いずれも存在しない場合は、指定されたIDを持つimg要素を返します。
一度特定の名前で要素が参照されると、その要素がIDまたはnameを変更しても、その名前を使用してこのメソッドでその要素を参照し続けることができますが、要素がツリー内にある限り有効です。
複数の一致する項目がある場合は、それらの要素を含むRadioNodeListオブジェクトが返されます。
form.submit()
すべての最新エンジンでサポートされています。
フォームを送信します。インタラクティブな制約検証をバイパスし、submitイベントを発生させません。
form.requestSubmit([ submitter ])
すべての最新エンジンでサポートされています。
フォームの送信を要求します。submit()とは異なり、このメソッドにはインタラクティブな制約検証とsubmitイベントの発生が含まれ、どちらも送信をキャンセルすることができます。
submitter引数を使用して、特定の送信ボタンを指すことができます。そのformaction、formenctype、formmethod、formnovalidate、およびformtarget属性が送信に影響を与える可能性があります。さらに、通常は除外されるボタンも送信のためのエントリリストの構築に含まれます。
form.reset()
すべての最新エンジンでサポートされています。
フォームをリセットします。
form.checkValidity()
フォームのコントロールがすべて有効であればtrueを返し、そうでなければfalseを返します。
form.reportValidity()
フォームのコントロールがすべて有効であればtrueを返し、そうでなければfalseを返し、ユーザーに通知します。
autocompleteIDL属性は、同じ名前のコンテンツ属性を反映しなければならず、既知の値のみが許可される。
すべての最新エンジンでサポートされています。
nameおよびrelIDL属性は、同じ名前のコンテンツ属性を反映しなければならない。
すべての最新エンジンでサポートされています。
acceptCharsetIDL属性は、accept-charsetコンテンツ属性を反映しなければならない。
relListIDL属性は、relコンテンツ属性を反映しなければならない。
elementsIDL属性は、form要素のルートに根ざしたHTMLFormControlsCollectionを返さなければならない。そのフィルタは、列挙された要素で、フォームの所有者がform要素であるものに一致しなければならないが、input要素でそのtype属性がImage
Button状態にあるものは、歴史的な理由からこのコレクションから除外されなければならない。
lengthIDL属性は、elementsコレクションによって表されるノードの数を返さなければならない。
サポートされているプロパティのインデックスは、その瞬間にelements属性によって返されたオブジェクトによってサポートされているインデックスです。
ユーザーエージェントがform要素のインデックス付きプロパティの値を決定するには、指定されたindexを引数として指定してitemメソッドをelementsコレクションで呼び出す際に返される値を返さなければならない。
各form要素は、過去の名前マップと呼ばれる名前から要素へのマッピングを持ちます。これは、名前が変更されてもコントロールの名前を保持するために使用されます。
サポートされているプロパティ名は、次のアルゴリズムから取得した名前で構成され、そのアルゴリズムから取得した順序で構成されます。
sourced namesを、文字列、要素、ソース(ソースはid、name、またはpastのいずれか)、およびソースがpastの場合は年齢で構成されるタプルの順序付きリストとします(初期は空です)。
form要素がinput要素で、そのtype属性がImage Button状態にあるものを除く、列挙された要素candidateごとに:
過去の名前マップ内の各エントリpast entryに対して、そのpast entryの名前を文字列として、past entryの要素を要素として、pastをソースとして、past entryが過去の名前マップに存在する時間の長さを年齢としてsourced namesにエントリを追加します。
sourced namesを、各タプルの要素エントリのツリー順序で並べ替え、同じ要素を持つエントリを、ソースがidのエントリを最初に、次にソースがnameのエントリを、最後にソースがpastのエントリを並べ、同じ要素とソースを持つエントリを年齢で並べ替え、最も古いものを最初にします。
名前が空文字列であるsourced namesのエントリを削除します。
マップ内の以前のエントリと同じ名前を持つsourced namesのエントリを削除します。
sourced namesから名前のリストを返し、その相対的な順序を維持します。
ユーザーエージェントがform要素の名前付きプロパティの値を決定するには、次の手順を実行しなければならない。
candidatesをライブのRadioNodeListオブジェクトとし、列挙された要素のすべてを含むものとし、そのフォームの所有者がform要素であり、nameに等しいid属性またはname属性を持つものとしますが、input要素でそのtype属性がImage Button状態にあるものを除きます。
candidatesが空の場合、candidatesをライブのRadioNodeListオブジェクトとし、img要素のすべてを含むものとし、そのフォームの所有者がform要素であり、nameに等しいid属性またはname属性を持つものとします。
candidatesが空の場合、nameがform要素の過去の名前マップ内のエントリの1つである場合、そのマップ内のnameに関連付けられたオブジェクトを返します。
candidatesに複数のノードが含まれている場合、candidatesを返します。
それ以外の場合、candidatesには正確に1つのノードが含まれています。このノードにnameからのマッピングを追加し、以前に同じ名前のエントリが存在する場合はそれを置き換えます。
candidatesのノードを返します。
あるform要素の過去の名前マップにリストされている要素がフォームの所有者を変更した場合、そのエントリはそのマップから削除されなければなりません。
submit()メソッドのステップは、submitted from
submit() methodをtrueに設定し、submitをthisから実行することです。
requestSubmit(submitter)メソッドが呼び出された場合、次のステップを実行しなければなりません:
submitterがnullでない場合:
submitterがsubmit buttonでない場合、TypeErrorをスローします。
submitterのform ownerがこのform要素でない場合、"NotFoundError"DOMExceptionをスローします。
そうでない場合、submitterをこのform要素に設定します。
reset()メソッドが呼び出された場合、次のステップを実行しなければなりません:
form要素がリセットのためにロックされていますとマークされている場合、リターンします。
form要素をリセットのためにロックされたとマークします。
form要素のリセットのためにロックされたマークを解除します。
checkValidity()メソッドが呼び出された場合、ユーザーエージェントはform要素の制約を静的に検証し、制約検証がpositiveな結果を返した場合はtrueを、negativeな結果を返した場合はfalseを返さなければなりません。
reportValidity()メソッドが呼び出された場合、ユーザーエージェントはform要素の制約をインタラクティブに検証し、制約検証がpositiveな結果を返した場合はtrueを、negativeな結果を返した場合はfalseを返さなければなりません。
この例は、2つの検索フォームを示しています:
< form action = "https://www.google.com/search" method = "get" >
< label > Google: < input type = "search" name = "q" ></ label > < input type = "submit" value = "Search..." >
</ form >
< form action = "https://www.bing.com/search" method = "get" >
< label > Bing: < input type = "search" name = "q" ></ label > < input type = "submit" value = "Search..." >
</ form >
label要素すべての現在のエンジンでサポートされています。
すべての現在のエンジンでサポートされています。
label要素を含まない。for — ラベルをフォームコントロールに関連付けます
[Exposed =Window ]
interface HTMLLabelElement : HTMLElement {
[HTMLConstructor ] constructor ();
readonly attribute HTMLFormElement ? form ;
[CEReactions ] attribute DOMString htmlFor ;
readonly attribute HTMLElement ? control ;
};
label要素は、ユーザーインターフェースのキャプションを表します。このキャプションは、label要素のラベル付けされたコントロールと呼ばれる特定のフォームコントロールに関連付けることができます。for属性を使用するか、label要素の内部にフォームコントロールを配置することで、関連付けられます。
以下のルールで特に指定されていない限り、label要素には、ラベル付けされたコントロールはありません。
すべての現在のエンジンでサポートされています。
for属性は、キャプションが関連付けられるフォームコントロールを示すために指定することができます。この属性が指定されている場合、その属性の値は、label要素と同じツリー内のIDでなければなりません。また、その属性が指定され、かつfor属性の値に等しいIDを持つ要素がlabel要素のラベル付けされたコントロールです。
for属性が指定されていないが、label要素にラベル付け可能な要素の子孫がある場合、ツリー順で最初のそのような子孫が、label要素のラベル付けされたコントロールです。
label要素の正確なデフォルトの表示と動作、特にプラットフォームのラベル動作と一致するはずです。label要素のイベントに対するアクティベーション動作は何であれ、label要素のインタラクティブなコンテンツの子孫、およびそのインタラクティブなコンテンツの子孫を対象とするイベントのアクティベーション動作は何も行わない必要があります。
フォーム関連のカスタム要素はラベル付け可能な要素であるため、label要素のアクティベーション動作がラベル付けされたコントロールに影響を与える場合、組み込み要素とカスタム要素の両方に影響を与えます。
例えば、ラベルをクリックするとフォームコントロールがアクティブになるプラットフォームでは、次のスニペットの
labelをクリックすると、
ユーザーエージェントがinput要素にクリックイベントを発火させる可能性があります。
これは、ユーザーがその要素自体をトリガーしたかのような挙動です:
< label >< input type = checkbox name = lost > Lost</ label >
同様に、my-checkboxがフォーム関連のカスタム要素として宣言されていると仮定すると、次のコードも同じ動作をします。
< label >< my-checkbox name = lost ></ my-checkbox > Lost</ label >
この場合も、my-checkbox要素でクリックイベントが発火されます。
他のプラットフォームでは、どちらの場合もコントロールにフォーカスするか、何もしないかの挙動になるかもしれません。
次の例は、ラベル付きの3つのフォームコントロールを示しています。そのうち2つは、ユーザーが使用するための適切な形式を示す小さなテキストが含まれています。
< p >< label > Full name: < input name = fn > < small > Format: First Last</ small ></ label ></ p >
< p >< label > Age: < input name = age type = number min = 0 ></ label ></ p >
< p >< label > Post code: < input name = pc > < small > Format: AB12 3CD</ small ></ label ></ p >
label.control
現在のすべてのエンジンでサポートされています。
この要素に関連付けられているフォームコントロールを返します。
label.form
現在のすべてのエンジンでサポートされています。
この要素に関連付けられているフォームコントロールのフォームオーナーを返します。
関連付けられているフォームオーナーがない場合はnullを返します。
すべての現行エンジンでサポートされています。
htmlFor
IDL属性は、反映する必要があります for コンテンツ属性。
control
IDL属性は、次のステップを実行する必要があります:
label
要素にラベル付きコントロールがない場合、nullを返します。
label
要素のラベル付きコントロールが
フォーム関連要素でない場合は、nullを返します。
label
要素のラベル付きコントロールの
フォーム所有者 (それでもnullの可能性があります) を返します。
form
label要素のIDL属性は、リストされた フォーム関連要素のIDL属性とは異なり、formコンテンツ属性を持ちません。
control.labels
すべての現行エンジンでサポートされています。
すべての現行エンジンでサポートされています。
すべての現行エンジンでサポートされています。
すべての現行エンジンでサポートされています。
すべての現行エンジンでサポートされています。
すべての現行エンジンでサポートされています。
すべての現行エンジンでサポートされています。
フォームコントロールに関連付けられているすべての NodeList
を返します。
ラベル可能な要素とすべての input 要素には、
ライブな NodeList
オブジェクトが関連付けられており、これは
label 要素のリストを
表します。このリストは、ツリー順であり、その ラベル付きコントロールが該当する要素です。
labels IDL 属性は、ラベル可能な要素であって、フォーム関連のカスタム要素ではないもの、および
labels IDL 属性を持つ input 要素が取得されるとき、
その NodeList
オブジェクトを返さなければなりません。そして、この値は常に返される必要がありますが、
該当する要素が input 要素で、その type
属性が
の状態にある場合は、代わりに null を返す必要があります。
すべての現行エンジンでサポートされています。
フォーム関連のカスタム要素には
labels IDL 属性はありません。
代わりに、
その
ElementInternals オブジェクト
には
labels IDL 属性があります。取得時に、"NotSupportedError" DOMException
をスローしなければならないのは、ターゲット要素が フォーム関連のカスタム要素でない場合です。それ以外の場合、同じ NodeList
オブジェクトを返す必要があり、常に同じ値を返さなければなりません。
この(非準拠の)例は、NodeList
と labels
がどのように変化するか、および
input 要素が
type
属性を変更されたときに何を返すかを示しています。
<!doctype html>
< p >< label >< input ></ label ></ p >
< script >
const input = document. querySelector( 'input' );
const labels = input. labels;
console. assert( labels. length === 1 );
input. type = 'hidden' ;
console. assert( labels. length === 0 ); // inputはもはやラベルのラベル付きコントロール ではありません
console. assert( input. labels === null );
input. type = 'checkbox' ;
console. assert( labels. length === 1 ); // inputは再びラベルのラベル付きコントロール です
console. assert( input. labels === labels); // 最初に返された値と同じです
</ script >
input 要素すべての現行エンジンでサポートされています。
すべての現行エンジンでサポートされています。
type 属性が
非表示 の状態に ない 場合: インタラクティブコンテンツ.
type 属性が
非表示 の状態に ない 場合: リスト可能, ラベル可能, サブミット可能, リセット可能, および オートキャピタライズ継承 フォーム関連要素.
type 属性が
非表示
状態の場合: リスト可能, サブミット可能, リセット可能, および オートキャピタライズ継承 フォーム関連要素.
type 属性が
非表示 の状態に ない 場合: 触覚コンテンツ.
accept — ファイルアップロードコントロールで予想されるファイルタイプのヒント
alt — 画像が利用できない場合に使用する代替テキスト
autocomplete
— フォームの自動入力機能のヒント
checked —
コントロールがチェックされているかどうか
dirname — フォーム送信時に要素の方向性を送信するために使用するフォームコントロールの名前
disabled —
フォームコントロールが無効かどうか
form — 要素を フォーム要素に関連付ける
formaction — URL を フォーム送信に使用する
formenctype — エントリリストエンコーディングタイプを フォーム送信に使用する
formmethod — フォーム送信に使用するバリアント
formnovalidate
— フォーム送信のためのフォームコントロール検証をバイパスする
formtarget — ナビゲーブル を フォーム送信のために使用する
height — 垂直次元
list — オートコンプリートオプションのリスト
max — 最大値
maxlength —
値の最大長さ
min — 最小値
minlength —
値の最小長さ
multiple —
複数の値を許可するかどうか
name — 要素の名前
フォーム送信 および form.elements
API で使用する
pattern —
フォームコントロールの値が一致するパターン
placeholder
— フォームコントロール内に配置されるユーザーに見えるラベル
popovertarget —
ポップオーバー要素をトグル、表示、または非表示にするターゲット
popovertargetaction
— 対象のポップオーバー要素がトグルされるか、表示されるか、または非表示にされるかを示す
readonly —
ユーザーによる値の編集を許可するかどうか
required —
フォーム送信のためにコントロールが必要かどうか
size — コントロールのサイズ
src — リソースのアドレス
step —
フォームコントロールの値が一致するグラニュラリティ
type — フォームコントロールのタイプ
value — フォームコントロールの値
width — 水平次元
title 属性もあります。:
pattern
属性と一緒に使用された場合のパターンの説明
type 属性が
非表示
状態の場合:
著者向け; 実装者向け。
type 属性が
テキスト状態の場合: 著者向け; 実装者向け。
type 属性が
検索状態の場合:
著者向け; 実装者向け。
type 属性が
電話状態の場合: 著者向け; 実装者向け。
type 属性が
URL状態の場合: 著者向け; 実装者向け。
type 属性が
メール
状態の場合: 著者向け; 実装者向け。
type 属性が
パスワード
状態の場合: 著者向け; 実装者向け。
type 属性が
日付状態の場合:
著者向け; 実装者向け。
type 属性が
月
状態の場合: 著者向け; 実装者向け。
type 属性が
週 状態の場合:
著者向け; 実装者向け。
type 属性が
時間 状態の場合:
著者向け; 実装者向け。
type 属性が
ローカル日付および時刻状態の場合:
著者向け; 実装者向け。
type 属性が
数値状態の場合:
著者向け; 実装者向け。
type 属性が
範囲
状態の場合: 著者向け; 実装者向け。
type 属性が
色状態の場合:
著者向け; 実装者向け。
type 属性が
チェックボックス状態の場合: 著者向け; 実装者向け。
type 属性が
ラジオボタン状態の場合: 著者向け; 実装者向け。
type 属性が
ファイルアップロード状態の場合: 著者向け; 実装者向け。
type 属性が
サブミットボタン状態の場合: 著者向け; 実装者向け。
type 属性が
イメージボタン状態の場合: 著者向け; 実装者向け。
type 属性が
リセットボタン状態の場合: 著者向け; 実装者向け。
type 属性が
ボタン状態の場合:
著者向け; 実装者向け。
[Exposed =Window ]
interface HTMLInputElement : HTMLElement {
[HTMLConstructor ] constructor ();
[CEReactions ] attribute DOMString accept ;
[CEReactions ] attribute DOMString alt ;
[CEReactions ] attribute DOMString autocomplete ;
[CEReactions ] attribute boolean defaultChecked ;
attribute boolean checked ;
[CEReactions ] attribute DOMString dirName ;
[CEReactions ] attribute boolean disabled ;
readonly attribute HTMLFormElement ? form ;
attribute FileList ? files ;
[CEReactions ] attribute USVString formAction ;
[CEReactions ] attribute DOMString formEnctype ;
[CEReactions ] attribute DOMString formMethod ;
[CEReactions ] attribute boolean formNoValidate ;
[CEReactions ] attribute DOMString formTarget ;
[CEReactions ] attribute unsigned long height ;
attribute boolean indeterminate ;
readonly attribute HTMLDataListElement ? list ;
[CEReactions ] attribute DOMString max ;
[CEReactions ] attribute long maxLength ;
[CEReactions ] attribute DOMString min ;
[CEReactions ] attribute long minLength ;
[CEReactions ] attribute boolean multiple ;
[CEReactions ] attribute DOMString name ;
[CEReactions ] attribute DOMString pattern ;
[CEReactions ] attribute DOMString placeholder ;
[CEReactions ] attribute boolean readOnly ;
[CEReactions ] attribute boolean required ;
[CEReactions ] attribute unsigned long size ;
[CEReactions ] attribute USVString src ;
[CEReactions ] attribute DOMString step ;
[CEReactions ] attribute DOMString type ;
[CEReactions ] attribute DOMString defaultValue ;
[CEReactions ] attribute [LegacyNullToEmptyString ] DOMString value ;
attribute object ? valueAsDate ;
attribute unrestricted double valueAsNumber ;
[CEReactions ] attribute unsigned long width ;
undefined stepUp (optional long n = 1);
undefined stepDown (optional long n = 1);
readonly attribute boolean willValidate ;
readonly attribute ValidityState validity ;
readonly attribute DOMString validationMessage ;
boolean checkValidity ();
boolean reportValidity ();
undefined setCustomValidity (DOMString error );
readonly attribute NodeList ? labels ;
undefined select ();
attribute unsigned long ? selectionStart ;
attribute unsigned long ? selectionEnd ;
attribute DOMString ? selectionDirection ;
undefined setRangeText (DOMString replacement );
undefined setRangeText (DOMString replacement , unsigned long start , unsigned long end , optional SelectionMode selectionMode = "preserve");
undefined setSelectionRange (unsigned long start , unsigned long end , optional DOMString direction );
undefined showPicker ();
// also has obsolete members
};
HTMLInputElement includes PopoverInvokerElement ;
input
要素は、通常、ユーザーがデータを編集できるフォームコントロールを伴う型付きデータフィールドを 表します。
type
属性は、要素のデータ型(および関連するコントロール)を制御します。これは、以下のキーワードと状態を持つ 列挙型属性 です:
| キーワード | 状態 | データ型 | コントロールタイプ |
|---|---|---|---|
hidden |
任意の文字列 | n/a | |
text |
テキスト | 改行なしのテキスト | テキストコントロール |
search |
検索 | 改行なしのテキスト | 検索コントロール |
tel |
電話 | 改行なしのテキスト | テキストコントロール |
url |
URL | 絶対URL | テキストコントロール |
email |
メール | メールアドレスまたはメールアドレスのリスト | テキストコントロール |
password |
パスワード | 改行なしのテキスト(機密情報) | データ入力を隠すテキストコントロール |
date |
日付 | タイムゾーンなしの日付(年、月、日) | 日付コントロール |
month |
月 | タイムゾーンなしの年と月からなる日付 | 月コントロール |
week |
週 | タイムゾーンなしの週年番号と週番号からなる日付 | 週コントロール |
time |
時間 | タイムゾーンなしの時間(時、分、秒、秒の小数) | 時間コントロール |
datetime-local |
ローカル日付と時刻 | タイムゾーンなしの日付と時刻(年、月、日、時、分、秒、秒の小数) | 日付と時刻のコントロール |
number |
数値 | 数値 | テキストコントロールまたはスピナーコントロール |
range |
範囲 | 数値(正確な値が重要でない追加の意味を持つ) | スライダーコントロールまたは類似のもの |
color |
色 | 8ビットの赤、緑、青の成分を持つsRGBカラー | カラーピッカー |
checkbox |
チェックボックス | 事前に定義されたリストからの0またはそれ以上の値のセット | チェックボックス |
radio |
ラジオボタン | 列挙型の値 | ラジオボタン |
file |
ファイルアップロード | 各々がMIMEタイプとオプションでファイル名を持つゼロまたはそれ以上のファイル | ラベルとボタン |
submit |
送信ボタン | 列挙型の値で、選択された最後の値でなければならず、フォーム送信を開始する追加の意味を持つ | ボタン |
image |
イメージボタン | 特定の画像のサイズに対して相対的な座標で、選択された最後の値でなければならず、フォーム送信を開始する追加の意味を持つ | クリック可能な画像またはボタン |
reset |
リセットボタン | n/a | ボタン |
button |
ボタン | n/a | ボタン |
この属性の欠落値デフォルト と 無効値デフォルト はどちらも テキスト 状態です。
accept、
alt、
autocomplete、
checked、
dirname、
formaction、
formenctype、
formmethod、
formnovalidate、
formtarget、
height、
list、
max、
maxlength、
min、
minlength、
multiple、
pattern、
placeholder、
readonly、
required、
size、
src、
step、 および
width のコンテンツ属性、
checked、
files、
valueAsDate、
valueAsNumber、
list の IDL 属性、
select()
メソッド、
selectionStart、
selectionEnd、
selectionDirection
の IDL 属性、
setRangeText()
および
setSelectionRange()
メソッド、
stepUp()
および
stepDown()
メソッド、
input
および
change イベント が
input 要素に適用されるかどうかは、
type 属性の状態によります。
各タイプを定義するサブセクションは、これらの機能が適用されるものと適用されないものを明確に定義しており、これらの機能の動作は、それが適用されるかどうかによって異なります(例を参照してください。コンテンツ属性、API、イベント)。
次の表は規範的ではなく、これらのコンテンツ属性、IDL属性、メソッド、およびイベントのうち、各状態に適用されるものを要約しています:
| Text, Search | Telephone, URL | Password | Date, Month, Week, Time | Local Date and Time | Number | Range | Color | Checkbox, Radio Button | File Upload | Submit Button | Image Button | Reset Button, Button | |||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| コンテンツ属性 | |||||||||||||||
accept
| · | · | · | · | · | · | · | · | · | · | · | はい | · | · | · |
alt
| · | · | · | · | · | · | · | · | · | · | · | · | · | はい | · |
autocomplete
| はい | はい | はい | はい | はい | はい | はい | はい | はい | はい | · | · | · | · | · |
checked
| · | · | · | · | · | · | · | · | · | · | はい | · | · | · | · |
dirname
| はい | はい | はい | はい | はい | · | · | · | · | · | · | · | はい | · | · |
formaction
| · | · | · | · | · | · | · | · | · | · | · | · | はい | はい | · |
formenctype
| · | · | · | · | · | · | · | · | · | · | · | · | はい | はい | · |
formmethod
| · | · | · | · | · | · | · | · | · | · | · | · | はい | はい | · |
formnovalidate
| · | · | · | · | · | · | · | · | · | · | · | · | はい | はい | · |
formtarget
| · | · | · | · | · | · | · | · | · | · | · | · | はい | はい | · |
height
| · | · | · | · | · | · | · | · | · | · | · | · | · | はい | · |
list
| · | はい | はい | はい | · | はい | はい | はい | はい | はい | · | · | · | · | · |
max
| · | · | · | · | · | はい | はい | はい | はい | · | · | · | · | · | · |
maxlength
| · | はい | はい | はい | はい | · | · | · | · | · | · | · | · | · | · |
min
| · | · | · | · | · | はい | はい | はい | はい | · | · | · | · | · | · |
minlength
| · | はい | はい | はい | はい | · | · | · | · | · | · | · | · | · | · |
multiple
| · | · | · | はい | · | · | · | · | · | · | · | はい | · | · | · |
pattern
| · | はい | はい | はい | はい | · | · | · | · | · | · | · | · | · | · |
placeholder
| · | はい | はい | はい | はい | · | · | はい | · | · | · | · | · | · | · |
popovertarget
| · | · | · | · | · | · | · | · | · | · | · | · | はい | はい | はい |
popovertargetaction
| · | · | · | · | · | · | · | · | · | · | · | · | はい | はい | はい |
readonly
| · | はい | はい | はい | はい | はい | はい | はい | · | · | · | · | · | · | · |
required
| · | はい | はい | はい | はい | はい | はい | はい | · | · | はい | はい | · | · | · |
size
| · | はい | はい | はい | はい | · | · | · | · | · | · | · | · | · | · |
src
| · | · | · | · | · | · | · | · | · | · | · | · | · | はい | · |
step
| · | · | · | · | · | はい | はい | はい | はい | · | · | · | · | · | · |
width
| · | · | · | · | · | · | · | · | · | · | · | · | · | はい | · |
| IDL属性とメソッド | |||||||||||||||
checked
| · | · | · | · | · | · | · | · | · | · | はい | · | · | · | · |
files
| · | · | · | · | · | · | · | · | · | · | · | はい | · | · | · |
value
| default | value | value | value | value | value | value | value | value | value | default/on | filename | default | default | default |
valueAsDate
| · | · | · | · | · | はい | · | · | · | · | · | · | · | · | · |
valueAsNumber
| · | · | · | · | · | はい | はい | はい | はい | · | · | · | · | · | · |
list
| · | はい | はい | はい | · | はい | はい | はい | はい | はい | · | · | · | · | · |
select()
| · | はい | はい | はい† | はい | はい† | はい† | はい† | · | はい† | · | はい† | · | · | · |
selectionStart
| · | はい | はい | · | はい | · | · | · | · | · | · | · | · | · | · |
selectionEnd
| · | はい | はい | · | はい | · | · | · | · | · | · | · | · | · | · |
selectionDirection
| · | はい | はい | · | はい | · | · | · | · | · | · | · | · | · | · |
setRangeText()
| · | はい | はい | · | はい | · | · | · | · | · | · | · | · | · | · |
setSelectionRange()
| · | はい | はい | · | はい | · | · | · | · | · | · | · | · | · | · |
stepDown()
| · | · | · | · | · | はい | はい | はい | はい | · | · | · | · | · | · |
stepUp()
| · | · | · | · | · | はい | はい | はい | はい | · | · | · | · | · | · |
| イベント | |||||||||||||||
input
イベント
| · | はい | はい | はい | はい | はい | はい | はい | はい | はい | はい | はい | · | · | · |
change イベント
| · | はい | はい | はい | はい | はい | はい | はい | はい | はい | はい | はい | · | · | · |
† コントロールに選択可能なテキストがない場合、select()
メソッドはno-opとなり、"InvalidStateError" DOMExceptionは発生しません。
type
属性のいくつかの状態は、値の
サニタイズアルゴリズムを定義しています。
各input要素には、
値があり、それは
value IDL属性で公開されます。いくつかの状態は、
文字列を数値に変換するアルゴリズム、
数値を文字列に変換するアルゴリズム、
文字列をDateオブジェクトに変換するアルゴリズム、
及びDateオブジェクトを文字列に変換するアルゴリズムを定義しており、これらは
max、
min、
step、
valueAsDate、
valueAsNumber、
及びstepUp()によって使用されます。
input要素の
dirty valueフラグは、
ユーザーがコントロールを操作して値が変更されるたびにtrueに設定されなければなりません。(このフラグは、
valueIDL属性の定義に記述されているように、
値がプログラムによって変更されたときにもtrueに設定されます。)
value
コンテンツ属性は、デフォルト値を与えます。
input
要素のデフォルト値です。 value
コンテンツ属性が追加、設定、または削除された場合、コントロールのdirty
valueフラグ
がfalseであれば、ユーザーエージェントは、要素の値を
valueコンテンツ属性の値に設定しなければならず、
それが存在しない場合は空文字列に設定しなければならず、定義されている場合は現在の値のサニタイズアルゴリズムを実行しなければなりません。
各input要素には、
checkednessがあり、
それはcheckedIDL属性で公開されます。
各input要素には
boolean dirty checkednessフラグがあります。それがtrueの場合、
要素はdirty checkednessを持つと言われます。
dirty
checkednessフラグは、
要素が作成されたときにfalseに初期設定され、ユーザーがコントロールを操作してcheckednessが変更されたときにtrueに設定されなければなりません。
現在のすべてのエンジンでサポートされています。
checked
コンテンツ属性はブール属性であり、
input要素のデフォルト
checkednessを指定します。
checkedコンテンツ属性が追加された場合、
コントロールにdirty
checkednessがない場合、
ユーザーエージェントは要素のcheckednessを
trueに設定しなければならず、
checkedコンテンツ属性が削除された場合、
コントロールにdirty
checkednessがない場合、
ユーザーエージェントは要素のcheckednessを
falseに設定しなければなりません。
リセットアルゴリズムは、
input
要素のユーザーの妥当性、
dirty valueフラグ、
及びdirty
checkednessフラグ
をfalseに戻し、値を
valueコンテンツ属性の値に設定し、
それが存在しない場合は空文字列に設定し、checkednessを
trueに設定します。もし要素にcheckedコンテンツ属性があり、falseであれば、
選択されたファイルのリストを空にし、
値のサニタイズアルゴリズムを呼び出し、
type属性の現在の状態が一つを定義している場合に実行します。
各input要素は、
変更可能です。特に指定がない限り、
input要素は常に
変更可能です。同様に、
特に指定がない限り、ユーザーエージェントは要素の値またはcheckednessをユーザーが変更することを許可すべきではありません。
input
要素が無効にされた場合、それは
変更可能ではなくなります。
readonly
属性はまた、いくつかの
場合(例えば、Date
状態など)において、input要素が
変更可能であることを停止することがあります。
クローンステップ
は、input要素の
値、dirty valueフラグ、checkedness、及びdirty checkednessフラグを
クローン元のノードからコピーに伝播しなければなりません。
アクティベーションの挙動は、input要素
elementと
eventが与えられた場合、次の手順で行われます:
elementの入力アクティベーションの挙動を実行し、 その他の場合は何も行いません。
elementに対してポップオーバーターゲット属性のアクティベーション挙動を実行します。
要素のアクティベーションの挙動は、ユーザーが開始したアクティベーションおよび(el.click()のような)シンセティックなアクティベーションの両方で実行されます。
ユーザーエージェントは、ここでは指定されていない、特定のコントロールに対する動作も持つ場合がありますが、それらは本当にユーザーが開始したアクティベーションによってのみトリガーされます。一般的な選択肢は、コントロールに適用される場合は
ピッカーを表示すること
です。これに対し、入力アクティベーションの挙動は、特定の歴史的ケースにおいてのみピッカーを表示します(ファイルアップロードおよび
カラー状態)。
レガシーな事前アクティベーションの挙動は、input要素の場合、次の手順で行われます:
この要素のtype
属性がチェックボックス状態の場合、この要素の
checkednessを反対の値(つまり、falseであればtrue、trueであればfalse)に設定し、
この要素のindeterminateIDL属性をfalseに設定します。
この要素のtype
属性がラジオボタン状態の場合、この要素の
ラジオボタングループ内で
checkednessがtrueに設定されている要素への参照を取得し、それが存在する場合、この要素の
checkednessをtrueに設定します。
レガシーなキャンセルされたアクティベーションの挙動は、
input要素の場合、次の手順で行われます:
要素のtype
属性がチェックボックス状態の場合、要素の
checkednessおよび要素の
indeterminateIDL属性を、
レガシーな事前アクティベーションの挙動が実行される前の値に戻します。
この要素のtype
属性がラジオボタン状態の場合、
レガシーな事前アクティベーションの挙動で取得された要素への参照がまだ存在し、かつ現在この要素の
ラジオボタングループに属している場合、
その要素のcheckednessをtrueに設定します。そうでない場合、そのような要素が存在しなかった場合、またはその要素がもはやこの要素の
ラジオボタングループに存在しない場合、またはこの要素がもはや
ラジオボタングループに属していない場合、この要素の
checkednessをfalseに設定します。
input要素が
最初に作成されたとき、要素のレンダリングと動作はtype
属性の状態に定義されたレンダリングと動作に設定され、値のサニタイズアルゴリズムが定義されている場合には、それを呼び出さなければなりません。
input要素の
type属性が
状態を変更した場合、ユーザーエージェントは次の手順を実行しなければなりません:
要素の以前のtype
属性の状態がvalue
IDL属性をvalueモードにしており、要素の値が空文字列でない場合、そして要素の
type
属性の新しい状態がvalue
IDL属性をdefaultモードまたはdefault/onモードにする場合、要素の
value
コンテンツ属性を要素の値に設定します。
それ以外の場合で、要素の以前のtype
属性の状態がvalue
IDL属性をvalueモード以外のモードにしており、要素のtype
属性の新しい状態がvalue
IDL属性をvalueモードにする場合、要素の値を
value
コンテンツ属性の値に設定し、それが存在しない場合は空文字列に設定し、その後コントロールのdirty valueフラグを
falseに設定します。
それ以外の場合で、要素の以前のtype
属性の状態がvalue
IDL属性をfilenameモード以外のモードにしており、要素の
type
属性の新しい状態がvalue
IDL属性をfilenameモードにする場合、要素の値を
空文字列に設定します。
要素のレンダリングと動作を新しい状態に更新します。
要素のタイプ変更を通知します。(ラジオボタン状態がこれを特に使用します。)
値のサニタイズアルゴリズムを
呼び出します(type
属性の新しい状態に対して定義されている場合)。
previouslySelectableを、setRangeText()
が以前に要素に適用された場合はtrue、そうでない場合はfalseとします。
nowSelectableを、setRangeText()
が今適用された場合はtrue、そうでない場合はfalseとします。
previouslySelectableがfalseでnowSelectableがtrueの場合、要素のテキストエントリーカーソルの位置を
テキストコントロールの先頭に設定し、選択方向を「none」に設定します。
name属性は要素の名前を表します。
dirname属性は、
要素の書字方向が
どのように送信されるかを制御します。
disabled
属性は、コントロールを非インタラクティブにし、その値が送信されないようにするために使用されます。
form属性は、
input要素を
そのフォームオーナーと明示的に関連付けるために使用されます。
autocomplete
属性は、ユーザーエージェントがオートフィル機能をどのように提供するかを制御します。
HTMLInputElement#indeterminate
現在のすべてのエンジンでサポートされています。
indeterminateIDL属性は、初期設定でfalseに設定されなければなりません。取得時には、設定された最後の値を返さなければなりません。設定時には、新しい値に設定されなければなりません。チェックボックスコントロールの外観を変更する以外には効果はありません。
現在のすべてのエンジンでサポートされています。
accept,
alt, max, min, multiple,
pattern,
placeholder, required, size, src, および
stepIDL
属性は、それぞれのコンテンツ属性を
反映しなければなりません。
dirName
IDL属性は、dirnameコンテンツ
属性を反映しなければなりません。
readOnly
IDL
属性はreadonlyコンテンツ
属性を反映しなければなりません。
defaultCheckedIDL属性は
反映しなければなりません
checkedコンテンツ
属性。
defaultValueIDL属性は反映しなければなりません
valueコンテンツ
属性。
typeIDL
属性は、それぞれのコンテンツ属性を反映しなければなりません
既知の
値にのみ制限されます。maxLengthIDL属性は反映しなければなりません
maxlengthコンテンツ
属性、
非負の数値にのみ制限されます。
minLengthIDL属性は反映しなければなりません
minlengthコンテンツ
属性、
非負の数値にのみ制限されます。
IDL属性widthおよびheightは、画像がレンダリングされている
場合の画像のレンダリングされた幅と高さを
CSSピクセルで
返さなければなりません。または
画像が利用可能だがレンダリングされていない場合は、画像の自然な幅と高さを
CSSピクセルで返さなければなりません。画像が利用可能でない場合は0を返さなければなりません。
input
要素のtype
属性がイメージボタン状態でない場合、画像は利用可能ではありません。[CSS]
設定時には、それらはそれぞれのコンテンツ属性を反映するかのように振る舞わなければなりません。
willValidate、
validity、およびvalidationMessage
IDL属性、さらにcheckValidity()、
reportValidity()、
およびsetCustomValidity()
メソッドは、
制約検証APIの一部です。labels
IDL属性は、要素のラベルのリストを提供します。
select()、
selectionStart、
selectionEnd、
selectionDirection、
setRangeText()、
およびsetSelectionRange()
メソッドとIDL属性は、要素のテキスト選択を公開します。
disabled、
form、およびnameIDL属性は、
要素のフォームAPIの一部です。
type属性の状態type=hidden)現在のすべてのエンジンでサポートされています。
要素の 属性が 状態にある場合、このセクションのルールが適用されます。
要素は ユーザーが確認または操作することを意図していない値を。
制約バリデーション: 要素の 属性が 状態にある場合、。
属性が 存在し、その値が""と マッチである場合、 要素の 属性は 省略されなければなりません。
および コンテンツ属性がこの要素にされます。
IDL属性がこの要素にされ、 モードはです。
次のコンテンツ属性は指定されず、要素に: , , , , , , , , , , , , , , , , , , , , , , , , 。
次のIDL属性およびメソッドは要素に: , , , , , , , IDL属性; , , , , メソッド。
および イベントは。
type=text)状態およびSearch状態 (type=search)現在のすべてのエンジンでサポートされています。
現在のすべてのエンジンでサポートされています。
input
要素のtype
属性が
Text
状態またはSearch
状態にある場合、このセクションのルールが適用されます。
input
要素は、その要素のvalueのための1行のプレーンテキスト編集コントロールを表します。
Text 状態とSearch 状態の違いは主にスタイルに関するものです。検索コントロールが通常のテキストコントロールと区別されるプラットフォームでは、Search 状態では、通常のテキストコントロールとは異なる外観がプラットフォームの検索コントロールと一致する可能性があります。
要素がmutableである場合、そのvalueはユーザーによって編集可能であるべきです。ユーザーエージェントは、 ユーザーが要素のvalueにU+000A LINE FEED (LF)またはU+000D CARRIAGE RETURN (CR)文字を挿入することを許可してはなりません。
要素がmutableである場合、ユーザーエージェントはユーザーが要素の書字方向を変更し、左から右への書字方向または右から左への書字方向に設定できるようにするべきです。ユーザーがこれを行った場合、ユーザーエージェントは次のステップを実行しなければなりません。
ユーザーが左から右への書字方向を選択した場合、要素のdir
属性を"ltr"
に、ユーザーが右から左への書字方向を選択した場合は"rtl"
に設定します。
要素のタスクをキューに入れる、
ユーザーインタラクションタスクソースに対して
要素を指定し、イベントを発火させる input
と名付けられたイベントを要素に対して、bubbles
およびcomposed
属性をtrueに初期化して発火させます。
value
属性が指定されている場合、その値にはU+000A LINE FEED (LF)またはU+000D CARRIAGE RETURN (CR)文字が含まれてはなりません。
値のサニタイズアルゴリズムは次のとおりです: 改行を削除する要素のvalueから。
次の共通のinput
要素の内容
属性、IDL属性、およびメソッドは要素に適用されます:
autocomplete,
dirname,
list,
maxlength,
minlength,
pattern,
placeholder,
readonly,
required,
および
size
内容属性;
list,
selectionStart,
selectionEnd,
selectionDirection,
および
value
IDL属性;
select(),
setRangeText(),
および
setSelectionRange()
メソッド。
次の内容属性は指定してはならず、要素に適用されません:
accept,
alt,
checked,
formaction,
formenctype,
formmethod,
formnovalidate,
formtarget,
height,
max,
min,
multiple,
popovertarget,
popovertargetaction,
src,
step,
および
width。
次のIDL属性およびメソッドは要素に適用されません:
checked,
files,
valueAsDate,
および
valueAsNumber
IDL属性;
stepDown()
および
stepUp()
メソッド。
type=tel)すべての現在のエンジンでサポートされています。
input 要素の type 属性が 電話
状態にある場合、このセクションの規則が適用されます。
input 要素は、要素の 値 に与えられた電話番号を編集するためのコントロールを 表します。
要素が 変更可能 であれば、その 値 はユーザーによって編集可能であるべきです。ユーザーエージェントは、ユーザーが入力した 値 の間隔や、慎重に扱って句読点を変更する場合があります。ユーザーエージェントは、ユーザーが U+000A LINE FEED (LF) または U+000D CARRIAGE RETURN (CR) 文字を要素の 値 に挿入することを許可してはなりません。
value
属性が指定されている場合、その値には U+000A LINE FEED (LF) または U+000D CARRIAGE RETURN (CR) 文字が含まれてはなりません。
値の消毒アルゴリズム: 値から改行を削除 します。
URL 型および Email
型とは異なり、電話
型では特定の構文は強制されません。これは意図的なものであり、実際には電話番号フィールドは自由形式のフィールドであることが多いためです。特定の形式を強制する必要があるシステムには、pattern
属性や、クライアントサイドの検証メカニズムにフックするための setCustomValidity()
メソッドを使用することを推奨します。
次の共通 input
要素のコンテンツ属性、IDL属性、およびメソッドが要素に適用されます:
autocomplete,
dirname,
list,
maxlength,
minlength,
pattern,
placeholder,
readonly,
required,
size コンテンツ属性;
list,
selectionStart,
selectionEnd,
selectionDirection,
value IDL 属性;
select(),
setRangeText(),
setSelectionRange()
メソッド。
input
および change イベントは、適用されます。
次のコンテンツ属性は指定されるべきではなく、要素に 適用されません:
accept,
alt,
checked,
formaction,
formenctype,
formmethod,
formnovalidate,
formtarget,
height,
max,
min,
multiple,
popovertarget,
popovertargetaction,
src,
step,
width。
次のIDL属性およびメソッドは要素に 適用されません:
checked,
files,
valueAsDate,
valueAsNumber
IDL 属性;
stepDown()
stepUp() メソッド。
type=url)すべての現在のエンジンでサポートされています。
input 要素の type 属性が URL
状態にある場合、このセクションの規則が適用されます。
input 要素は、要素の 値 に与えられた単一の 絶対URL を編集するためのコントロールを 表します。
要素が 変更可能 であれば、ユーザーエージェントは、ユーザーがその 値 で表されるURLを変更できるようにする必要があります。ユーザーエージェントは、ユーザーが 有効な 絶対URL でない文字列を 値 として設定することを許可する場合がありますが、代わりに、ユーザーが入力した文字を自動的にエスケープして、値 が常に 有効な 絶対URL となるようにすることもできます(たとえそれがユーザーインターフェイスでユーザーが実際に見て編集した値でなくても)。ユーザーエージェントは、ユーザーが 値 を空文字列に設定できるようにする必要があります。ユーザーエージェントは、ユーザーが U+000A LINE FEED (LF) または U+000D CARRIAGE RETURN (CR) 文字を 値 に挿入することを許可してはなりません。
value
属性が指定されており、かつ空でない場合、その値は、スペースで囲まれる可能性のある有効なURL であり、かつ 絶対URL でなければなりません。
値の消毒アルゴリズム: 値から改行を削除 し、次に 先頭および末尾のASCII空白を削除 します。
制約の検証: 要素の 値 が空文字列でなく、かつ 有効な 絶対URL でない間、要素は 型の不一致が発生 します。
次の共通 input
要素のコンテンツ属性、IDL属性、およびメソッドが要素に適用されます:
autocomplete,
dirname,
list,
maxlength,
minlength,
pattern,
placeholder,
readonly,
required,
および
size コンテンツ属性;
list,
selectionStart,
selectionEnd,
selectionDirection,
および
value IDL 属性;
select(),
setRangeText(),
および
setSelectionRange()
メソッド。
input
および change イベントが 適用 されます。
次のコンテンツ属性は指定されるべきではなく、要素に 適用されません:
accept,
alt,
checked,
formaction,
formenctype,
formmethod,
formnovalidate,
formtarget,
height,
max,
min,
multiple,
popovertarget,
popovertargetaction,
src,
step,
および
width。
次のIDL属性およびメソッドは要素に 適用されません:
checked,
files,
valueAsDate,
および
valueAsNumber
IDL 属性;
stepDown()
および
stepUp() メソッド。
ドキュメントに次のマークアップが含まれていた場合:
< input type = "url" name = "location" list = "urls" >
< datalist id = "urls" >
< option label = "MIME: Format of Internet Message Bodies" value = "https://www.rfc-editor.org/rfc/rfc2045" >
< option label = "HTML" value = "https://html.spec.whatwg.org/" >
< option label = "DOM" value = "https://dom.spec.whatwg.org/" >
< option label = "Fullscreen" value = "https://fullscreen.spec.whatwg.org/" >
< option label = "Media Session" value = "https://mediasession.spec.whatwg.org/" >
< option label = "The Single UNIX Specification, Version 3" value = "http://www.unix.org/version3/" >
</ datalist >
...そして、ユーザーが "spec.w" と入力し、ユーザーエージェントがユーザーが最近
https://url.spec.whatwg.org/#url-parsing および https://streams.spec.whatwg.org/
にアクセスしたことを見つけた場合、レンダリングは次のように見えるかもしれません:
このサンプルの最初の4つのURLは、ユーザーが入力したテキストに一致する、作成者指定のリスト内の4つのURLであり、実装定義の 方法でソートされています(おそらく、ユーザーがそのURLを参照する頻度によるものです)。UAがURLの値を使用して、ユーザーがスキーム部分を省略し、ドメイン名でインテリジェントなマッチングを行えることに注意してください。
このサンプルの最後の2つのURL(そしておそらく、スクロールバーのさらなる値の利用可能性の指示に基づいて、さらに多くのURLがあるでしょう)は、ユーザーエージェントのセッション履歴データからの一致です。このデータはページDOMには提供されません。この特定のケースでは、UAにはそれらの値に対応するタイトルが提供されていません。
type=email)すべての最新エンジンでサポートされています。
input要素のtype属性がEmail状態である場合、このセクションのルールが適用されます。
Email状態の動作は、multiple属性が指定されているかどうかに依存します。
multiple属性が要素に指定されていない場合
input要素は、要素のvalueで指定されたメールアドレスを編集するためのコントロールを表します。
要素が変更可能な場合、ユーザーエージェントはユーザーにそのvalueで表されるメールアドレスを変更できるようにする必要があります。ユーザーエージェントは、valueを有効なメールアドレスではない文字列に設定できるようにすることがあります。ユーザーエージェントは、ユーザーが単一のメールアドレスを提供することを期待していると想定して動作するべきです。ユーザーエージェントは、ユーザーにvalueを空の文字列に設定させるべきです。ユーザーエージェントは、ユーザーがvalueにU+000Aラインフィード(LF)またはU+000Dキャリッジリターン(CR)文字を挿入することを許可してはいけません。ユーザーエージェントは表示と編集のためにvalueを変換することがあります。特に、ユーザーエージェントはvalueのドメインラベルにおけるPunycodeを表示においてIDNに変換し、逆も同様に行うべきです。
制約検証: ユーザーインターフェースがPunycodeに変換できない入力を表している場合、コントロールは無効な入力を受けていると見なされます。
value属性が指定されていて空でない場合、その値は有効なメールアドレスである必要があります。
値のサニタイズアルゴリズムは次の通りです: 改行を削除する 値から、次に先頭と末尾のASCII空白を削除します 値から。
制約検証: 要素の値が空の文字列でもなく、単一の有効なメールアドレスでもない場合、要素はタイプミスマッチを受けていると見なされます。
multiple属性が要素に指定されている場合
input要素は、要素の値に指定されたメールアドレスを追加、削除、および編集するためのコントロールを表します。
要素が変更可能な場合、ユーザーエージェントはユーザーにその値で表されるメールアドレスを追加、削除、および編集できるようにするべきです。ユーザーエージェントは、リスト内の任意の個別の値を有効なメールアドレスでない文字列に設定できるようにすることがありますが、ユーザーがU+002Cコンマ(,)やU+000Aラインフィード(LF)、U+000Dキャリッジリターン(CR)文字を含む文字列に設定することを許可してはいけません。ユーザーエージェントは、要素の値にあるすべてのアドレスを削除できるようにするべきです。ユーザーエージェントは表示と編集のために値を変換することがあります。特に、ユーザーエージェントは値のドメインラベルにおけるPunycodeを表示においてIDNに変換し、逆も同様に行うべきです。
制約検証: ユーザーインターフェースがU+002Cコンマ(,)を含む個別の値またはユーザーエージェントがPunycodeに変換できない入力を表している場合、コントロールは無効な入力を受けていると見なされます。
ユーザーが要素の値を変更するたびに、ユーザーエージェントは次の手順を実行する必要があります:
最新の値を要素の値のコピーにします。
先頭と末尾のASCII空白を削除します 最新の値内の各値から。
要素の値を最新の値のすべての値を単一のU+002Cコンマ文字(,)で区切って連結した結果にします。リストの順序を維持します。
value属性が指定されている場合、その値は有効なメールアドレスリストである必要があります。
値のサニタイズアルゴリズムは次の通りです:
コンマで分割します 要素の値を、先頭と末尾のASCII空白を削除します 各結果のトークンから(存在する場合)、要素の値を(おそらく空の)トークンのリストにします。元の順序を維持します。
制約検証: 要素の値が有効なメールアドレスリストでない場合、要素はタイプミスマッチを受けていると見なされます。
multiple属性が設定または削除されると、ユーザーエージェントは値のサニタイズアルゴリズムを実行する必要があります。
有効なメールアドレスとは、次のABNFのemail生成に一致する文字列であり、その文字セットはUnicodeです。このABNFは、RFC
1123で説明されている拡張機能を実装しています。 [ABNF] [RFC5322] [RFC1034] [RFC1123]
email = 1* ( atext / "." ) "@" label * ( "." label )
label = let-dig [ [ ldh-str ] let-dig ] ; 限定されます 63文字まで RFC 1034 セクション 3.5
atext = < as defined in RFC 5322 セクション 3 .2 .3 >
let-dig = < as defined in RFC 1034 セクション 3 .5 >
ldh-str = < as defined in RFC 1034 セクション 3 .5 >
この要件は、RFC 5322の意図的な違反であり、RFC 5322は、"@"文字の前に対して厳しすぎ、"@"文字の後では曖昧で、(コメント、空白文字、引用符付き文字列を許可するなど)実際の使用には馴染みのない方法で許容しているため、ここでは実用的ではありません。
以下のJavaScriptおよびPerl互換の正規表現は、上記の定義を実装したものです。
/^[a-zA-Z0-9.!#$%&'*+\/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$/
有効なメールアドレスリストとは、カンマ区切りのトークンの集合であり、各トークンがそれ自体が有効なメールアドレスである場合です。有効なメールアドレスリストからトークンのリストを取得するには、実装は文字列をカンマで分割します。
次の共通のinput要素のコンテンツ属性、IDL属性、およびメソッドが要素に適用されます:
autocomplete,
dirname,
list,
maxlength,
minlength,
multiple,
pattern,
placeholder,
readonly,
required,
および
sizeコンテンツ属性;
listおよびvalueIDL属性;
select()
メソッド。
次のコンテンツ属性は指定されるべきではなく適用されません要素に:
accept,
alt,
checked,
formaction,
formenctype,
formmethod,
formnovalidate,
formtarget,
height,
max,
min,
popovertarget,
popovertargetaction,
src,
step,
および
width。
次のIDL属性およびメソッド適用されません要素に:
checked,
files,
selectionStart,
selectionEnd,
selectionDirection,
valueAsDate,
および
valueAsNumberIDL属性;
stepDown()
および
stepUp()メソッド。
type=password)すべての現行エンジンでサポートされています。
input 要素の
type 属性が パスワード 状態にある場合、このセクションのルールが適用されます。
input 要素は、要素の
値
のための一行のプレーンテキスト編集コントロールを表します。ユーザーエージェントは、ユーザー以外の人がそれを見られないように値を隠す必要があります。
要素が 可変 である場合、その 値 はユーザーが編集可能であるべきです。ユーザーエージェントは、ユーザーが U+000A LINE FEED (LF) や U+000D CARRIAGE RETURN (CR) 文字を 値 に挿入することを許可してはいけません。
指定されている場合、 value
属性には、U+000A LINE FEED (LF) や U+000D CARRIAGE RETURN (CR) 文字が含まれていない値を持つ必要があります。
値のサニタイズアルゴリズム は次の通りです: 改行を削除 して 値 を処理します。
次の一般的な input
要素のコンテンツ属性、IDL 属性、およびメソッドは、要素に 適用されます:
autocomplete,
dirname,
maxlength,
minlength,
pattern,
placeholder,
readonly,
required,
size コンテンツ属性;
selectionStart,
selectionEnd,
selectionDirection,
value IDL 属性;
select(),
setRangeText(),
setSelectionRange()
メソッド。
value IDL
属性は、モード value
にあります。
次の input
および change イベントが 適用されます。
次のコンテンツ属性は指定されてはならず、要素に 適用されません:
accept,
alt,
checked,
formaction,
formenctype,
formmethod,
formnovalidate,
formtarget,
height,
list,
max,
min,
multiple,
popovertarget,
popovertargetaction,
src,
step,
width。
次の IDL 属性およびメソッドは要素に 適用されません:
checked,
files,
list,
valueAsDate,
valueAsNumber
IDL 属性;
stepDown()
stepUp()
メソッド。
type=date)すべての現行エンジンでサポートされています。
input 要素の type 属性が 日付
状態にある場合、このセクションのルールが適用されます。
input 要素は、要素の 値 を特定の 日付 を表す文字列に設定するためのコントロールを表します。
要素が 可変 である場合、ユーザーエージェントは、ユーザーがその 日付 を変更できるようにする必要があります。ユーザーエージェントは、 有効な日付文字列 ではない非空の文字列を 値 に設定することを許可してはいけません。ユーザーエージェントがユーザーが 日付 を選択するためのインターフェースを提供する場合、その 値 は、ユーザーの選択を表す 有効な日付文字列 に設定されなければなりません。ユーザーエージェントは、ユーザーが 値 を空の文字列に設定できるようにする必要があります。
制約の検証: ユーザーインターフェースが、ユーザーエージェントが 有効な日付文字列 に変換できない入力を記述している間、コントロールは 不正な入力 によって影響を受けています。
日付、時間、および数値フォームコントロールの入力形式と送信形式の違いについての議論や、フォームコントロールのローカライズに関する 導入セクション と 実装ノート を参照してください。
value
属性が指定されていて、かつ空でない場合、その値は 有効な日付文字列
でなければなりません。
値のサニタイズアルゴリズム は次の通りです: 要素の 値 が 有効な日付文字列 でない場合、それを空の文字列に設定します。
min 属性が指定されている場合、その値は 有効な日付文字列 でなければなりません。 max 属性が指定されている場合、その値は 有効な日付文字列 でなければなりません。
step 属性は日数で表されます。 ステップスケールファクター は
86,400,000 であり(他のアルゴリズムで使用されるミリ秒に日数を変換します)。 デフォルトステップ は 1 日です。
要素が ステップの不一致 によって影響を受けている場合、ユーザーエージェントは要素の 値 を最も近い 日付 に丸めることができます。
文字列を数値に変換するアルゴリズム は次の通りです:
文字列 input が与えられたとき、 日付を解析する とエラーになる場合はエラーを返します。それ以外の場合は、1970-01-01 の朝の UTC
の午前零時(値 "1970-01-01T00:00:00.0Z" で表される時刻)から解析された 日付 の午前零時 UTC までのミリ秒数を返します。うるう秒は無視します。
数値を文字列に変換するアルゴリズム は次の通りです: 数値
input が与えられたとき、1970-01-01 の朝の UTC の午前零時(値 "1970-01-01T00:00:00.0Z" で表される時刻)から現在の
input ミリ秒後に UTC での時刻に相当する 有効な日付文字列 を返します。
文字列を Date オブジェクトに変換するアルゴリズム
は次の通りです: 文字列 input が与えられたとき、 日付を解析する とエラーになる場合はエラーを返します。それ以外の場合は、解析された 日付 の午前零時 UTC を表す新しい Date オブジェクト
を返します。
Date オブジェクトを文字列に変換するアルゴリズム は次の通りです: Date
オブジェクト input が与えられたとき、UTC タイムゾーンで input に相当する時刻の 日付 を表す 有効な日付文字列 を返します。
日付 状態(およびその後のセクションで説明される他の日付や時間に関連する状態)は、現代のカレンダーに対して正確な日付と時刻が確立できない値の入力を目的としたものではありません。例えば、「ビッグバンの1ミリ秒後」や「ジュラ紀の初期」、「紀元前250年頃の冬」などの時間の入力には不適切です。
グレゴリオ暦が導入される前の日付を入力する場合、著者は 日付
状態(およびその後のセクションで説明される他の日付や時間に関連する状態)を使用しないことをお勧めします。ユーザーエージェントは、以前の時代の日付や時間をグレゴリオ暦に変換することをサポートする必要はなく、ユーザーに手動でそれを行わせることはユーザーに過度の負担をかけます。(これは、グレゴリオ暦が異なる時期に異なる国で段階的に導入されたため、16世紀の途中から20世紀の初期にかけて異なります。)代わりに、著者は
select 要素と input 要素を使用して、 数値
状態を使用してきめ細かい入力コントロールを提供することをお勧めします。
次の一般的な input
要素のコンテンツ属性、IDL 属性、およびメソッドは、要素に 適用されます:
autocomplete,
list,
max,
min,
readonly,
required,
step コンテンツ属性;
list,
value,
valueAsDate,
valueAsNumber
IDL 属性;
select(),
stepDown(),
stepUp() メソッド。
value IDL 属性は、モード value にあります。
次の input
および change イベントが 適用されます。
次のコンテンツ属性は指定されてはならず、要素に 適用されません:
accept,
alt,
checked,
dirname,
formaction,
formenctype,
formmethod,
formnovalidate,
formtarget,
height,
maxlength,
minlength,
multiple,
pattern,
placeholder,
popovertarget,
popovertargetaction,
size,
src、
width。
次の IDL 属性およびメソッドは要素に 適用されません:
checked,
selectionStart,
selectionEnd,
selectionDirection
IDL 属性;
setRangeText(),
setSelectionRange()
メソッド。
type=month)すべての現行エンジンでサポートされています。
input 要素の type 属性が 月
状態にある場合、このセクションのルールが適用されます。
input 要素は、要素の 値 を特定の 月 を表す文字列に設定するためのコントロールを表します。
要素が 可変 である場合、ユーザーエージェントは、ユーザーがその 月 を変更できるようにする必要があります。ユーザーエージェントは、 有効な月の文字列 ではない非空の文字列を 値 に設定することを許可してはいけません。ユーザーエージェントがユーザーが 月 を選択するためのインターフェースを提供する場合、その 値 は、ユーザーの選択を表す 有効な月の文字列 に設定されなければなりません。ユーザーエージェントは、ユーザーが 値 を空の文字列に設定できるようにする必要があります。
制約の検証: ユーザーインターフェースが、ユーザーエージェントが 有効な月の文字列 に変換できない入力を記述している間、コントロールは 不正な入力 によって影響を受けています。
日付、時間、および数値フォームコントロールの入力形式と送信形式の違いについての議論や、フォームコントロールのローカライズに関する 導入セクション と 実装ノート を参照してください。
value
属性が指定されていて、かつ空でない場合、その値は 有効な月の文字列 でなければなりません。
値のサニタイズアルゴリズム は次の通りです: 要素の 値 が 有効な月の文字列 でない場合、それを空の文字列に設定します。
min 属性が指定されている場合、その値は 有効な月の文字列 でなければなりません。 max 属性が指定されている場合、その値は 有効な月の文字列 でなければなりません。
step 属性は月単位で表されます。 ステップスケールファクター は 1
であり(アルゴリズムでは月を使用するため変換は不要です)。 デフォルトステップ は 1 ヶ月です。
要素が ステップの不一致 によって影響を受けている場合、ユーザーエージェントは要素の 値 を最も近い 月 に丸めることができます。
文字列を数値に変換するアルゴリズム は次の通りです: 文字列 input が与えられたとき、 月を解析する とエラーになる場合はエラーを返します。それ以外の場合は、1970年1月から解析された 月 までの月数を返します。
数値を文字列に変換するアルゴリズム は次の通りです: 数値 input が与えられたとき、1970年1月から現在の input 月後に相当する 有効な月の文字列 を返します。
文字列を Date
オブジェクトに変換するアルゴリズム は次の通りです: 文字列 input が与えられたとき、 月を解析する とエラーになる場合はエラーを返します。それ以外の場合は、解析された 月 の最初の日の午前零時 UTC を表す新しい Date オブジェクト
を返します。
Date オブジェクトを文字列に変換するアルゴリズム は次の通りです: Date
オブジェクト input が与えられたとき、UTC タイムゾーンで input に相当する時刻の 月 を表す 有効な月の文字列 を返します。
次の一般的な input
要素のコンテンツ属性、IDL 属性、およびメソッドは、要素に 適用されます:
autocomplete,
list,
max,
min,
readonly,
required,
step コンテンツ属性;
list,
value,
valueAsDate,
valueAsNumber
IDL 属性;
select(),
stepDown(),
stepUp() メソッド。
value IDL 属性は、モード
value にあります。
次の input
および change イベントが 適用されます。
次のコンテンツ属性は指定されてはならず、要素に 適用されません:
accept,
alt,
checked,
dirname,
formaction,
formenctype,
formmethod,
formnovalidate,
formtarget,
height,
maxlength,
minlength,
multiple,
pattern,
placeholder,
popovertarget,
popovertargetaction,
size,
src、
width。
次の IDL 属性およびメソッドは要素に 適用されません:
checked,
files,
selectionStart,
selectionEnd,
selectionDirection
IDL 属性;
setRangeText(),
setSelectionRange()
メソッド。
type=week) input 要素の type 属性が 週
状態にある場合、このセクションのルールが適用されます。
input 要素は、要素の 値 を特定の 週 を表す文字列に設定するためのコントロールを表します。
要素が 可変 である場合、ユーザーエージェントは、ユーザーがその 週 を変更できるようにする必要があります。ユーザーエージェントは、 有効な週の文字列 ではない非空の文字列を 値 に設定することを許可してはいけません。ユーザーエージェントがユーザーが 週 を選択するためのインターフェースを提供する場合、その 値 は、ユーザーの選択を表す 有効な週の文字列 に設定されなければなりません。ユーザーエージェントは、ユーザーが 値 を空の文字列に設定できるようにする必要があります。
制約の検証: ユーザーインターフェースが、ユーザーエージェントが 有効な週の文字列 に変換できない入力を記述している間、コントロールは 不正な入力 によって影響を受けています。
日付、時間、および数値フォームコントロールの入力形式と送信形式の違いについての議論や、フォームコントロールのローカライズに関する 導入セクション と 実装ノート を参照してください。
value
属性が指定されていて、かつ空でない場合、その値は 有効な週の文字列
でなければなりません。
値のサニタイズアルゴリズム は次の通りです: 要素の 値 が 有効な週の文字列 でない場合、それを空の文字列に設定します。
min 属性が指定されている場合、その値は 有効な週の文字列 でなければなりません。 max 属性が指定されている場合、その値は 有効な週の文字列 でなければなりません。
step 属性は週単位で表されます。 ステップスケールファクター は
604,800,000 であり(他のアルゴリズムで使用されるミリ秒に週を変換します)。 デフォルトステップ は 1 週間です。 デフォルトステップベース は −259,200,000 です(1970-W01
の週の開始)。
要素が ステップの不一致 によって影響を受けている場合、ユーザーエージェントは要素の 値 を最も近い 週 に丸めることができます。
文字列を数値に変換するアルゴリズム は次の通りです:
文字列 input が与えられたとき、 週を解析する とエラーになる場合はエラーを返します。それ以外の場合は、1970-01-01 の朝の UTC
の午前零時(値 "1970-01-01T00:00:00.0Z" で表される時刻)から解析された週の月曜日の午前零時 UTC までのミリ秒数を返します。うるう秒は無視します。
数値を文字列に変換するアルゴリズム は次の通りです: 数値
input が与えられたとき、1970-01-01 の朝の UTC の午前零時(値 "1970-01-01T00:00:00.0Z" で表される時刻)から現在の
input ミリ秒後に UTC での時刻に相当する 有効な週の文字列 を返します。
文字列を Date オブジェクトに変換するアルゴリズム
は次の通りです: 文字列 input が与えられたとき、 週を解析する とエラーになる場合はエラーを返します。それ以外の場合は、解析された週の月曜日の午前零時 UTC
を表す新しい Date
オブジェクト を返します。
Date オブジェクトを文字列に変換するアルゴリズム は次の通りです: Date
オブジェクト input が与えられたとき、UTC タイムゾーンで input に相当する時刻の 週 を表す 有効な週の文字列 を返します。
次の一般的な input
要素のコンテンツ属性、IDL 属性、およびメソッドは、要素に 適用されます:
autocomplete,
list,
max,
min,
readonly,
required,
step コンテンツ属性;
list,
value,
valueAsDate,
valueAsNumber
IDL 属性;
select(),
stepDown(),
stepUp() メソッド。
value IDL 属性は、モード value にあります。
次の input
および change イベントが 適用されます。
次のコンテンツ属性は指定されてはならず、要素に 適用されません:
accept,
alt,
checked,
dirname,
formaction,
formenctype,
formmethod,
formnovalidate,
formtarget,
height,
maxlength,
minlength,
multiple,
pattern,
placeholder,
popovertarget,
popovertargetaction,
size,
src、
width。
次の IDL 属性およびメソッドは要素に 適用されません:
checked,
files,
selectionStart,
selectionEnd,
selectionDirection
IDL 属性;
setRangeText(),
setSelectionRange()
メソッド。
type=time)すべての最新エンジンでサポートされています。
input 要素の type 属性が 時間
状態にある場合、このセクションのルールが適用されます。
input 要素は、要素の 値 を特定の 時間 を表す文字列に設定するためのコントロールを表します。
要素が 可変 である場合、ユーザーエージェントは、ユーザーがその 時間 を変更できるようにする必要があります。ユーザーエージェントは、 有効な時間の文字列 ではない非空の文字列を 値 に設定することを許可してはいけません。ユーザーエージェントがユーザーが 時間 を選択するためのインターフェースを提供する場合、その 値 は、ユーザーの選択を表す 有効な時間の文字列 に設定されなければなりません。ユーザーエージェントは、ユーザーが 値 を空の文字列に設定できるようにする必要があります。
制約の検証: ユーザーインターフェースが、ユーザーエージェントが 有効な時間の文字列 に変換できない入力を記述している間、コントロールは 不正な入力 によって影響を受けています。
日付、時間、および数値フォームコントロールの入力形式と送信形式の違いについての議論や、フォームコントロールのローカライズに関する 導入セクション と 実装ノート を参照してください。
value
属性が指定されていて、かつ空でない場合、その値は 有効な時間の文字列 でなければなりません。
値のサニタイズアルゴリズム は次の通りです: 要素の 値 が 有効な時間の文字列 でない場合、それを空の文字列に設定します。
フォームコントロールには 周期的なドメインがあります。
min 属性が指定されている場合、その値は 有効な時間の文字列 でなければなりません。 max 属性が指定されている場合、その値は 有効な時間の文字列 でなければなりません。
step 属性は秒単位で表されます。 ステップスケールファクター は 1000
であり(他のアルゴリズムで使用されるミリ秒に秒を変換します)。 デフォルトステップ は 60 秒です。
要素が ステップの不一致 によって影響を受けている場合、ユーザーエージェントは要素の 値 を最も近い 時間 に丸めることができます。
文字列を数値に変換するアルゴリズム は次の通りです: 文字列 input が与えられたとき、 時間を解析する とエラーになる場合はエラーを返します。それ以外の場合は、午前零時から解析された 時間 までのミリ秒数を返します。
数値を文字列に変換するアルゴリズム は次の通りです: 数値 input が与えられたとき、午前零時から現在の input ミリ秒後の 時間 に相当する 有効な時間の文字列 を返します。
文字列を Date オブジェクトに変換するアルゴリズム
は次の通りです: 文字列 input が与えられたとき、 時間を解析する とエラーになる場合はエラーを返します。それ以外の場合は、1970-01-01 の UTC
で解析された 時間 を表す新しい Date オブジェクト
を返します。
Date オブジェクトを文字列に変換するアルゴリズム は次の通りです: Date
オブジェクト input が与えられたとき、UTC タイムゾーンで input に相当する時刻の 時間 を表す 有効な時間の文字列 を返します。
次の一般的な input
要素のコンテンツ属性、IDL 属性、およびメソッドは、要素に 適用されます:
autocomplete,
list,
max,
min,
readonly,
required,
step コンテンツ属性;
list,
value,
valueAsDate,
valueAsNumber
IDL 属性;
select(),
stepDown(),
stepUp() メソッド。
value IDL 属性は、モード value にあります。
次の input
および change イベントが 適用されます。
次のコンテンツ属性は指定されてはならず、要素に 適用されません:
accept,
alt,
checked,
dirname,
formaction,
formenctype,
formmethod,
formnovalidate,
formtarget,
height,
maxlength,
minlength,
multiple,
pattern,
placeholder,
popovertarget,
popovertargetaction,
size,
src、
width。
次の IDL 属性およびメソッドは要素に 適用されません:
checked,
files,
selectionStart,
selectionEnd,
selectionDirection
IDL 属性;
setRangeText(),
setSelectionRange()
メソッド。
type=datetime-local)すべての最新エンジンでサポートされています。
input
要素のtype
属性がローカル日時状態の場合、このセクションのルールが適用されます。
input
要素は、要素の値を設定するためのコントロールを表し、ローカル日時を表す文字列であり、タイムゾーンのオフセット情報は含まれません。
要素が変更可能である場合、ユーザーエージェントはユーザーがその要素の日時を変更できるようにする必要があります。また、ユーザーエージェントは、ユーザーが有効な正規化されたローカル日時の文字列でない非空の文字列に値を設定できないようにしなければなりません。ユーザーエージェントがローカル日時を選択するためのユーザーインターフェースを提供する場合、値は、ユーザーの選択を表す有効な正規化されたローカル日時の文字列に設定されなければなりません。ユーザーが値を空の文字列に設定できるようにするべきです。
制約の検証: ユーザーインターフェースがユーザーエージェントが有効な正規化されたローカル日時の文字列に変換できない入力を示している場合、そのコントロールは不正な入力が行われている状態です。
日付、時刻、および数値の形式の入力形式と送信形式の違いについては、導入セクションおよびフォームコントロールのローカライズに関する実装メモを参照してください。
値
属性が指定され、かつ空でない場合、その値は有効なローカル日時の文字列でなければなりません。
値のサニタイズアルゴリズムは次の通りです: 要素の値が有効なローカル日時の文字列である場合、それを同じ日時を表す有効な正規化されたローカル日時の文字列に設定します。そうでない場合、空の文字列に設定します。
min
属性が指定されている場合、その値は有効なローカル日時の文字列でなければなりません。max
属性が指定されている場合、その値は有効なローカル日時の文字列でなければなりません。
step
属性は秒単位で表現されます。ステップスケールファクターは1000です
(他のアルゴリズムで使用されるミリ秒に変換します)。デフォルトステップは60秒です。
要素がステップの不一致に苦しんでいる場合、ユーザーエージェントは要素の値を、その要素がステップの不一致に苦しまない最も近いローカル日時に丸めることができます。
文字列を数値に変換するアルゴリズムは次の通りです:
文字列inputを指定して、日時の解析がエラーとなる場合、エラーを返します。それ以外の場合は、1970-01-01の午前0時(値「1970-01-01T00:00:00.0」で表される時刻)から解析されたローカル日時まで経過したミリ秒数を返します。うるう秒は無視します。
数値を文字列に変換するアルゴリズムは次の通りです:
数値inputを指定して、1970-01-01の午前0時(値「1970-01-01T00:00:00.0」で表される時刻)のinputミリ秒後の日時を表す有効な正規化されたローカル日時の文字列を返します。
歴史的な日付に関する注記は、日付状態セクションにあります。
次の共通のinput要素のコンテンツ属性、IDL属性、およびメソッドが要素に適用されます:
autocomplete,
list,
max,
min,
readonly,
required,
および
step
コンテンツ属性;
list,
value,
および
valueAsNumber
IDL属性;
select(),
stepDown(),
および
stepUp()
メソッド。
次のコンテンツ属性は指定してはならず、要素に適用されません:
accept,
alt,
checked,
dirname,
formaction,
formenctype,
formmethod,
formnovalidate,
formtarget,
height,
maxlength,
minlength,
multiple,
pattern,
placeholder,
popovertarget,
popovertargetaction,
size,
src,
および
width。
次のIDL属性およびメソッドは要素に適用されません:
checked,
files,
selectionStart,
selectionEnd,
selectionDirection,
および
valueAsDate
IDL属性;
setRangeText(),
および
setSelectionRange()
メソッド。
次の例は、フライト予約アプリケーションの一部を示しています。このアプリケーションでは、input
要素にそのtype
属性をdatetime-localに設定し、選択した空港のタイムゾーンで指定された日時を解釈します。
< fieldset >
< legend > 目的地</ legend >
< p >< label > 空港: < input type = text name = to list = airports ></ label ></ p >
< p >< label > 出発時刻: < input type = datetime-local name = totime step = 3600 ></ label ></ p >
</ fieldset >
< datalist id = airports >
< option value = ATL label = "アトランタ" >
< option value = MEM label = "メンフィス" >
< option value = LHR label = "ロンドン・ヒースロー" >
< option value = LAX label = "ロサンゼルス" >
< option value = FRA label = "フランクフルト" >
</ datalist >
type=number)すべての最新エンジンでサポートされています。
input
要素のtype
属性が数値
状態の場合、このセクションのルールが適用されます。
input
要素は、その要素の値を数値を表す文字列に設定するためのコントロールを表します。
要素が変更可能である場合、ユーザーエージェントはユーザーがその要素の値で表される数値を変更できるようにすべきです。その数値は浮動小数点数の値を解析するルールを適用して取得されます。ユーザーエージェントは、値を有効な浮動小数点数ではない非空の文字列に設定することを許可してはなりません。ユーザーエージェントが数値を選択するためのユーザーインターフェースを提供する場合、値は、ユーザーの選択を表す浮動小数点数の最適な表現に設定されなければなりません。ユーザーが値を空の文字列に設定できるようにすべきです。
制約の検証: ユーザーインターフェースがユーザーエージェントが有効な浮動小数点数に変換できない入力を示している場合、そのコントロールは不正な入力が行われている状態です。
この仕様書では、ユーザーエージェントが使用するユーザーインターフェースを定義していません。ユーザーエージェントベンダーは、自社のユーザーのニーズに最も適した方法を考慮することをお勧めします。例えば、ペルシャ語やアラビア語市場のユーザーエージェントでは、ペルシャ語やアラビア語の数値入力に対応し(上記のように変換して送信形式に適合させます)、ローマ人向けのユーザーエージェントでは、値をローマ数字で表示する(または、より現実的には、フランス市場向けのユーザーエージェントでは、千単位のアポストロフィと小数点の前にコンマを使用して値を表示し、その方法で値を入力させることができ、内部的には上記の送信形式に変換します)などが考えられます。
値
属性が指定されており、かつ空でない場合、その値は有効な浮動小数点数でなければなりません。
値のサニタイズアルゴリズムは次の通りです: 要素の値が有効な浮動小数点数ではない場合、それを空の文字列に設定します。
min
属性が指定されている場合、その値は有効な浮動小数点数でなければなりません。max属性が指定されている場合、その値は有効な浮動小数点数でなければなりません。
ステップスケールファクターは1です。デフォルトステップは1です(ユーザーが整数のみを選択できるようにします。ただし、ステップベースに非整数値がある場合は除きます)。
要素がステップの不一致に苦しんでいる場合、ユーザーエージェントは要素の値を、その要素がステップの不一致に苦しまない最も近い数値に丸めることができます。そのような数値が2つある場合、ユーザーエージェントは無限大に最も近い方を選ぶことが推奨されます。
文字列を数値に変換するアルゴリズムは次の通りです: 文字列inputを指定して、浮動小数点数の値を解析するルールをinputに適用するとエラーが発生した場合、エラーを返します。それ以外の場合は、得られた数値を返します。
数値を文字列に変換するアルゴリズムは次の通りです: 数値inputを指定して、inputを表す有効な浮動小数点数を返します。
次の共通のinput
要素のコンテンツ属性、IDL属性、およびメソッドが要素に適用されます:
autocomplete,
list,
max,
min,
placeholder,
readonly,
required,
および
step
コンテンツ属性;
list,
value、
および
valueAsNumber
IDL属性;
select(),
stepDown()、
および
stepUp()
メソッド。
次のコンテンツ属性は指定してはならず、要素に適用されません:
accept,
alt,
checked,
dirname,
formaction,
formenctype,
formmethod,
formnovalidate,
formtarget,
height,
maxlength,
minlength,
multiple,
pattern,
popovertarget,
popovertargetaction,
size,
src、
および
width。
次のIDL属性およびメソッドは要素に適用されません:
checked,
files,
selectionStart,
selectionEnd,
selectionDirection,
および
valueAsDate
IDL属性;
setRangeText()、
および
setSelectionRange()
メソッド。
次に、数値入力コントロールの使用例を示します:
< label > いくら請求しますか? $< input type = number min = 0 step = 0.01 name = price ></ label >
上記のように、ユーザーエージェントはユーザーのローカル形式での数値入力をサポートし、それを上記で説明した形式に変換して送信することができます。これには、グループ区切り文字(「872,000,000,000」のように)やさまざまな小数点区切り文字(「3,99」と「3.99」など)の処理、あるいはアラビア語、デーヴァナーガリー文字、ペルシャ語、タイ語などのローカル数字を使用することが含まれる場合があります。
type=number
状態は、入力内容がたまたま数値のみで構成されているが、厳密には数値ではない場合には適切ではありません。例えば、クレジットカード番号やアメリカの郵便番号には適していません。type=numberを使用するかどうかを判断する簡単な方法は、入力コントロールにスピンボックスインターフェース(例えば、"up"および"down"の矢印)があるのが理にかなっているかどうかを考えることです。クレジットカード番号の最後の桁を1つ間違えることは、わずかな間違いではなく、すべての桁が間違っているのと同じくらい不適切です。したがって、ユーザーが"up"および"down"のボタンを使用してクレジットカード番号を選択するのは理にかなっていません。スピンボックスインターフェースが適切でない場合は、type=textが適切な選択である可能性があります(inputmodeまたはpattern属性を使用することを検討してください)。
type=range)すべての最新エンジンでサポートされています。
input
要素のtype
属性が範囲
状態の場合、このセクションのルールが適用されます。
input
要素は、その要素の値を数値を表す文字列に設定するためのコントロールを表します。ただし、正確な値は重要ではなく、数値状態よりも簡単なインターフェースをユーザーエージェントに提供できます。
要素が変更可能である場合、ユーザーエージェントはユーザーがその要素の値で表される数値を変更できるようにすべきです。その数値は浮動小数点数の値を解析するルールを適用して取得されます。ユーザーエージェントは、値を有効な浮動小数点数でない文字列に設定することを許可してはなりません。ユーザーエージェントが数値を選択するためのユーザーインターフェースを提供する場合、値は、ユーザーの選択を表す浮動小数点数の最適な表現に設定されなければなりません。ユーザーエージェントは、値を空の文字列に設定することを許可してはなりません。
制約の検証: ユーザーインターフェースがユーザーエージェントが有効な浮動小数点数に変換できない入力を示している場合、そのコントロールは不正な入力が行われている状態です。
値
属性が指定されており、かつ空でない場合、その値は有効な浮動小数点数でなければなりません。
値のサニタイズアルゴリズムは次の通りです: 要素の値が有効な浮動小数点数ではない場合、浮動小数点数としての最適な表現に設定します。それはデフォルト値です。
デフォルト値は、最小値と最大値の差の半分を足したものです。ただし、最大値が最小値よりも小さい場合、デフォルト値は最小値になります。
要素が下限に達している場合、ユーザーエージェントは要素の値を浮動小数点数としての最適な表現である最小値に設定しなければなりません。
要素が上限に達している場合、最大値が最小値よりも小さくない限り、ユーザーエージェントは要素の値を有効な浮動小数点数として設定しなければなりません。それは最大値です。
要素がステップの不一致に苦しんでいる場合、ユーザーエージェントは要素の値をその要素がステップの不一致に苦しまない最も近い数値に丸め、その数値は最小値以上であり、最大値が最小値よりも小さくない限り、最大値以下であることが条件です。この条件に合致する数値が2つある場合、ユーザーエージェントは正の無限大に最も近い数値を使用しなければなりません。
例えば、次のマークアップ<input type="range" min=0 max=100 step=20 value=50>は、初期値が60の範囲コントロールを生成します。
次に、list属性を使用した自動補完リストを持つ範囲コントロールの例を示します。これは、コントロールの全範囲に沿って特に重要な値が存在する場合に役立つことがあります。例えば、事前設定された照明レベルや速度制御に使用される範囲コントロール内の典型的な速度制限などです。次のマークアップフラグメントでは:
< input type = "range" min = "-100" max = "100" value = "0" step = "10" name = "power" list = "powers" >
< datalist id = "powers" >
< option value = "0" >
< option value = "-30" >
< option value = "30" >
< option value = "++50" >
</ datalist >
...次のスタイルシートを適用した場合:
input { writing-mode : vertical-lr; height : 75 px ; width : 49 px ; background : #D5CCBB; color : black; }
...次のように表示される場合があります:
ユーザーエージェントがスタイルシートで指定された高さと幅の比率からコントロールの向きを決定した点に注目してください。色も同様にスタイルシートから導出されました。ただし、目盛りはマークアップから導出されました。特に、step属性は目盛りの配置には影響を与えておらず、ユーザーエージェントは著者が指定した完了値のみを使用し、極端な位置に長い目盛りを追加することを決定しました。
無効な値++50が無視されたことにも注目してください。
別の例として、次のマークアップフラグメントを考えてみましょう:
< input name = x type = range min = 100 max = 700 step = 9.09090909 value = 509.090909 >
ユーザーエージェントは、例えば次のようにさまざまな方法で表示できます:
または、次のように表示できます:
ユーザーエージェントは、スタイルシートに指定された寸法に基づいて表示するものを選択できます。これにより、幅の違いにもかかわらず、目盛りの解像度を維持することができます。
最後に、2つのラベル付き値を持つ範囲コントロールの例を示します:
< input type = "range" name = "a" list = "a-values" >
< datalist id = "a-values" >
< option value = "10" label = "Low" >
< option value = "90" label = "High" >
</ datalist >
コントロールが垂直に描画されるようにスタイルを適用すると、次のように表示される場合があります:
この状態では、範囲とステップの制約がユーザー入力中にも強制され、値を空の文字列に設定する方法はありません。
min属性が指定されている場合、その値は有効な浮動小数点数でなければなりません。デフォルトの最小値は0です。max属性が指定されている場合、その値は有効な浮動小数点数でなければなりません。デフォルトの最大値
は100です。
ステップスケールファクターは1です。デフォルトステップは1です(min
属性に非整数値がある場合を除き、整数のみが許可されます)。
文字列を数値に変換するアルゴリズムは次の通りです: 文字列inputを指定して、浮動小数点数の値を解析するルールをinputに適用するとエラーが発生した場合、エラーを返します。それ以外の場合は、得られた数値を返します。
数値を文字列に変換するアルゴリズムは次の通りです: 数値inputを指定して、inputを表す浮動小数点数としての最適な表現を返します。
次の共通のinput
要素のコンテンツ属性、IDL属性、およびメソッドが要素に適用されます:
autocomplete,
list,
max,
min、
および
step
コンテンツ属性;
list、
value、
および
valueAsNumber
IDL属性;
stepDown()
および
stepUp()
メソッド。
次のコンテンツ属性は指定してはならず、要素に適用されません:
accept,
alt,
checked,
dirname,
formaction,
formenctype,
formmethod,
formnovalidate,
formtarget,
height,
maxlength、
minlength、
multiple、
pattern、
placeholder、
popovertarget、
popovertargetaction、
readonly、
required、
size、
src、
および
width。
次のIDL属性およびメソッドは要素に適用されません:
checked、
files、
selectionStart、
selectionEnd、
selectionDirection、
および
valueAsDate
IDL属性;
setRangeText()、
および
setSelectionRange()
メソッド。
type=color)すべての現行エンジンでサポートされています。
要素の input
属性の type
が
カラー
状態
の場合、このセクションのルールが適用されます。
input
要素は、色を設定するためのカラーホエールコントロールを
表します。
要素の 値 は、
シンプルな色 を表す文字列です。
この状態では、常に色が選択されており、値を空の文字列に設定する方法はありません。
要素が 変更可能 な場合、 ユーザーエージェントは、ユーザーが要素の 値 で表される色を変更できるようにする必要があります。 これは、 シンプルな色の値を解析するためのルール を適用して得られたものでなければなりません。ユーザーエージェントは、ユーザーが 値 を 有効な小文字のシンプルな色 以外の文字列に設定することを許可してはなりません。ユーザーエージェントが色を選択するためのユーザーインターフェイスを提供する場合、 値 はユーザーの選択に基づいて シンプルな色の値をシリアル化するためのルール を使用して設定されなければなりません。ユーザーエージェントは、ユーザーが 値 を空の文字列に設定することを許可してはなりません。
この要素の 入力 アクティベーション動作 は、要素に対して ピッカーを表示 します(該当する場合)。
制約のバリデーション: ユーザーインターフェイスが、 ユーザーエージェントが 有効な小文字のシンプルな色 に変換できない入力を示している場合、そのコントロールは 誤った入力を受けています。
値
属性が指定されていて、空でない場合、その値は
有効なシンプルな色
でなければなりません。
値のサニタイズアルゴリズム は次の通りです:
要素の 値 が
有効なシンプルな色
である場合、その値を 値
に設定し、要素を ASCII
小文字に変換します。それ以外の場合、文字列 "#000000" に設定します。
次の共通の input
要素のコンテンツ属性および IDL 属性が要素に適用されます:
autocomplete
と
list コンテンツ属性;
list および
value IDL 属性;
select()
メソッド。
input
および change イベントが
適用されます。
次のコンテンツ属性は指定されるべきではなく、
適用されません:
accept、
alt、
checked、
dirname、
formaction、
formenctype、
formmethod、
formnovalidate、
formtarget、
height、
max、
maxlength、
min、
minlength、
multiple、
pattern、
placeholder、
popovertarget、
popovertargetaction、
readonly、
required、
size、
src、
step、
width。
次の IDL 属性およびメソッドは要素に 適用されません:
checked、
files、
selectionStart、
selectionEnd、
selectionDirection、
valueAsDate
および、
valueAsNumber
IDL 属性;
setRangeText()、
setSelectionRange()、
stepDown()、
および
stepUp()
メソッド。
type=checkbox)すべての現在のエンジンでサポートされています。
input要素のtype属性がチェックボックスの状態にある場合、このセクションのルールが適用されます。
input要素は、要素のチェック状態を表す2つの状態の制御を表します。要素のチェック状態がtrueである場合、制御は肯定的な選択を表し、falseである場合は否定的な選択を表します。要素の不確定IDL属性がtrueに設定されている場合、制御の選択は、第3の不確定な状態にあるかのように隠されるべきです。
要素の不確定IDL属性がtrueに設定されている場合でも、制御は決して真の三状態制御にはなりません。不確定IDL属性は、単に第3の状態のように見せるだけです。
inputアクティベーション動作は、以下の手順を実行することです:
制約検証: 要素が必須であり、そのチェック状態がfalseである場合、要素は欠落しています。
input.indeterminate [ = value ]
設定されると、現在の値が表示されないようにチェックボックスコントロールのレンダリングをオーバーライドします。
次の共通input要素のコンテンツ属性とIDL属性が要素に適用されます:
checked,
requiredコンテンツ属性、
checkedおよび
valueIDL属性。
次のコンテンツ属性は指定されてはならず、適用されません:
accept,
alt,
autocomplete,
dirname,
formaction,
formenctype,
formmethod,
formnovalidate,
formtarget,
height,
list,
max,
maxlength,
min,
minlength,
multiple,
pattern,
placeholder,
popovertarget,
popovertargetaction,
readonly,
size,
src,
step,
width。
次のIDL属性とメソッドは、要素には適用されません:
files,
list,
selectionStart,
selectionEnd,
selectionDirection,
valueAsDate,
valueAsNumberIDL属性、
select(),
setRangeText(),
setSelectionRange(),
stepDown(),
stepUp()メソッド。
type=radio)すべての現在のエンジンでサポートされています。
input要素のtype属性がラジオボタンの状態にある場合、このセクションのルールが適用されます。
input要素は、他のinput要素と組み合わせて使用される場合、一つのコントロールだけがチェック状態をtrueにできるラジオボタングループを形成します。要素のチェック状態がtrueである場合、グループ内で選択されたコントロールを表し、falseである場合は選択されていないコントロールを示します。
ラジオボタングループに含まれるinput要素aには、次のすべての条件を満たす他のinput要素bも含まれます:
input要素bのtype属性がラジオボタンの状態にある。name属性を持ち、それらのname属性が空でなく、aのname属性の値がbのname属性の値と等しい。ツリーには、ラジオボタングループにその要素だけを含むinput要素を含めてはなりません。
次の現象のいずれかが発生した場合、その発生後に要素のチェック状態がtrueである場合、同じラジオボタングループ内の他のすべての要素のチェック状態をfalseに設定する必要があります:
name属性が設定、変更、または削除される。
inputアクティベーション動作は、次の手順を実行することです:
制約検証: ラジオボタングループ内の要素が必須であり、ラジオボタングループ内のすべてのinput要素のチェック状態がfalseである場合、その要素は欠落しています。
次の例では、何らかの理由で、プッパーが必須であり無効であることが指定されています:
< form >
< p >< label >< input type = "radio" name = "dog-type" value = "pupper" required disabled > Pupper</ label >
< p >< label >< input type = "radio" name = "dog-type" value = "doggo" > Doggo</ label >
< p >< button > Make your choice</ button >
</ form >
ユーザーがこのフォームを「Doggo」を選択せずに送信しようとすると、input要素の両方が欠落していますとなります。これは、ラジオボタングループ内の要素が必須(最初の要素)、かつラジオボタングループ内のすべての要素がfalseのチェック状態を持つためです。
一方、ユーザーが「Doggo」を選択してフォームを送信した場合、input要素のいずれも欠落していないとなります。これは、それらのいずれかが必須でありながら、すべての要素がfalseのチェック状態を持っていないためです。
ラジオボタングループ内のラジオボタンのいずれもチェックされていない場合、インターフェースでは最初はすべて未チェックのままになりますが、いずれかがチェックされるまで(ユーザーによってまたはスクリプトによって)未チェックのままとなります。
次の共通input要素のコンテンツ属性とIDL属性が要素に適用されます:
checkedおよび
requiredコンテンツ属性、
checkedおよび
valueIDL属性。
次のコンテンツ属性は指定されてはならず、適用されません:
accept,
alt,
autocomplete,
dirname,
formaction,
formenctype,
formmethod,
formnovalidate,
formtarget,
height,
list,
max,
maxlength,
min,
minlength,
multiple,
pattern,
placeholder,
popovertarget,
popovertargetaction,
readonly,
size,
src,
step,
width。
次のIDL属性とメソッドは、要素には適用されません:
files,
list,
selectionStart,
selectionEnd,
selectionDirection,
valueAsDate,
valueAsNumberIDL属性、
select(),
setRangeText(),
setSelectionRange(),
stepDown(),
stepUp()メソッド。
type=file)すべての現在のエンジンでサポートされています。
input要素のtype属性がファイルアップロードの状態にある場合、このセクションのルールが適用されます。
input要素は、ファイル名、ファイルタイプ、ファイルボディ(ファイルの内容)で構成される選択されたファイルのリストを表します。
ユーザーがディレクトリ階層全体や異なるディレクトリから同じ名前の複数のファイルを選択した場合でも、ファイル名にはパスコンポーネントを含めてはなりません。ファイルアップロードの状態におけるパスコンポーネントとは、ファイル名の部分で、U+005C REVERSE SOLIDUS 文字(\)で区切られた部分を指します。
multiple属性が設定されていない限り、選択されたファイルのリストには1つのファイルしか含めてはなりません。
このような要素elementのinputアクティベーション動作は、elementに対してピッカーを表示することです(該当する場合)。
要素が変更可能である場合、ユーザーエージェントはユーザーがドラッグアンドドロップなどの他の方法でもファイルを変更できるようにするべきです。ユーザーがそうした場合、ユーザーエージェントは要素のファイル選択を更新する必要があります。
要素が変更可能でない場合、ユーザーエージェントはユーザーが要素の選択を変更することを許可してはなりません。
要素elementのファイル選択を更新するには:
要素タスクをキューに追加する elementに対して、次のステップでユーザーインタラクションタスクソースを与える:
制約検証: 要素が必須であり、選択されたファイルのリストが空である場合、その要素は欠落しています。
すべての現在のエンジンでサポートされています。
すべての現在のエンジンでサポートされています。
accept属性を指定して、ユーザーエージェントにどのファイルタイプを受け入れるかのヒントを提供することができます。
指定された場合、属性はカンマ区切りのトークンセットで構成される必要があります。各トークンは次のいずれかに対してASCII大文字小文字を区別しない一致である必要があります:
audio/*"
video/*"
image/*"
トークンは他のトークンに対してASCII大文字小文字を区別しない一致であってはなりません(すなわち、重複は許可されません)。ユーザーエージェントが属性からトークンのリストを取得するためには、属性値をカンマで分割する必要があります。
ユーザーエージェントは、この属性の値を使用して、より適切なユーザーインターフェースを表示することができます。たとえば、値image/*が指定されている場合、ユーザーエージェントはユーザーにローカルカメラを使用するか、写真コレクションから写真を選択するオプションを提供できます。値audio/*が指定されている場合、ユーザーエージェントはヘッドセットマイクを使用してクリップを録音するオプションを提供できます。
ユーザーエージェントは、これらのトークンの1つ(または複数)によって受け入れられないファイルをユーザーが選択することを防止するべきです。
著者は、特定のフォーマットのデータを探す際には、MIMEタイプと対応する拡張子の両方を指定することを推奨します。
たとえば、Microsoft WordドキュメントをOpen Document Formatファイルに変換するアプリケーションを考えてみましょう。Microsoft WordドキュメントはさまざまなMIMEタイプと拡張子で説明されるため、サイトはいくつかを次のようにリストすることができます:
< input type = "file" accept = ".doc,.docx,.xml,application/msword,application/vnd.openxmlformats-officedocument.wordprocessingml.document" >
ファイルタイプをファイル拡張子でしか説明しないプラットフォームでは、ここにリストされた拡張子を使用して許可されたドキュメントをフィルタリングすることができます。一方、MIMEタイプを内部的に使用するシステムでは、MIMEタイプを使用して許可されたファイルを選択できます。拡張子は、システムで使用されるMIMEタイプに対応する既知の拡張子をマップする拡張子登録テーブルがある場合に使用できます。
拡張子は曖昧であることが多い(例:
".dat"拡張子を使用する形式は無数に存在し、ユーザーは通常、自分のファイルを簡単に".doc"拡張子にリネームできますが、実際にはMicrosoft
Wordドキュメントではない場合もあります)、またMIMEタイプは信頼性に欠けることが多い(例:
多くの形式には正式に登録されたタイプがなく、多くの形式は実際には異なるMIMEタイプでラベル付けされています)。著者は、クライアントから受信したデータは、クライアントが敵対的でなく、ユーザーエージェントがaccept属性の要件を完全に遵守していた場合でも、期待される形式ではないかもしれないことを認識する必要があります。
歴史的な理由により、valueIDL属性は、ファイル名に"C:\fakepath\"という文字列を付加します。一部のレガシーユーザーエージェントは実際にフルパスを含めていました(これはセキュリティ脆弱性でした)。その結果、valueIDL属性からファイル名を後方互換性のある方法で取得することは簡単ではありません。次の関数は、互換性のある方法でファイル名を抽出します:
function extractFilename( path) {
if ( path. substr( 0 , 12 ) == "C:\\fakepath\\" )
return path. substr( 12 ); // modern browser
var x;
x = path. lastIndexOf( '/' );
if ( x >= 0 ) // Unix-based path
return path. substr( x+ 1 );
x = path. lastIndexOf( '\\' );
if ( x >= 0 ) // Windows-based path
return path. substr( x+ 1 );
return path; // just the filename
}
これを次のように使用できます:
< p >< input type = file name = image onchange = "updateFilename(this.value)" ></ p >
< p > The name of the file you picked is: < span id = "filename" > (none)</ span ></ p >
< script >
function updateFilename( path) {
var name = extractFilename( path);
document. getElementById( 'filename' ). textContent = name;
}
</ script >
次の共通input要素のコンテンツ属性とIDL属性が要素に適用されます:
accept、
multiple、
requiredコンテンツ属性;
files、
valueIDL属性;
select()メソッド。
次のコンテンツ属性は指定されてはならず、適用されません:
alt、
autocomplete、
checked、
dirname、
formaction、
formenctype、
formmethod、
formnovalidate、
formtarget、
height、
list、
max、
maxlength、
min、
minlength、
pattern、
popovertarget、
popovertargetaction、
placeholder、
readonly、
size、
src、
step、
width。
要素のvalue属性は省略しなければなりません。
次のIDL属性とメソッドは、要素には適用されません:
checked、
list、
selectionStart、
selectionEnd、
selectionDirection、
valueAsDate、
valueAsNumberIDL属性;
setRangeText()、
setSelectionRange()、
stepDown()、
stepUp()メソッド。
type=submit)すべての現行エンジンでサポートされています。
あるinput
要素のtype
属性が
送信ボタン状態にある場合、このセクションのルールが適用されます。
input
要素は、アクティブ化されるとフォームを送信するボタンを表します。要素にvalue
属性がある場合、ボタンのラベルはその属性の値でなければなりません。そうでない場合、ラベルは「送信」などの意味を持つ実装定義の文字列でなければなりません。要素は
ボタンであり、特に送信ボタンです。
デフォルトのラベルが実装定義であるため、通常ボタンの幅はそのラベルに依存するため、ボタンの幅は少数の指紋情報を漏洩する可能性があります。この情報は、ユーザーエージェントの識別やユーザーのロケールと強く相関している可能性が高いです。
次のeventが発生した場合、要素の入力アクティベーション動作は以下の通りです:
要素にフォームオーナーがない場合は、リターンします。
要素のフォームを送信し、 フォームオーナーから要素をリターンし、ユーザー関与が eventのユーザー ナビゲーション 関与に設定されている場合。
formaction、
formenctype、
formmethod、
formnovalidate、
およびformtarget属性はフォーム送信のための属性です。
formnovalidate
属性は、制約検証をトリガーしない送信ボタンを作成するために使用できます。
次の共通input
要素のコンテンツ属性とIDL属性が要素に適用されます:
dirname、
formaction、
formenctype、
formmethod、
formnovalidate、
formtarget、
popovertarget、
および
popovertargetaction
コンテンツ属性;value
IDL
属性。
次のコンテンツ属性は指定されてはならず、要素に適用されません:
accept、
alt、
autocomplete、
checked、
height、
list、
max、
maxlength、
min、
minlength、
multiple、
pattern、
placeholder、
readonly、
required、
size、
src、
step、
width。
次のIDL属性とメソッドは、要素には適用されません:
checked、
files、
list、
selectionStart、
selectionEnd、
selectionDirection、
valueAsDate、
および
valueAsNumber
IDL属性;
select()、
setRangeText()、
setSelectionRange()、
stepDown()、
および
stepUp()
メソッド。
type=image)すべての現在のエンジンでサポートされています。
input要素の
type
属性が画像ボタンの状態である場合、このセクションのルールが適用されます。
input
要素は、ユーザーが座標を選択してフォームを送信できる画像、またはユーザーがフォームを送信できるボタンを表します。この要素はボタンであり、特に送信ボタンです。
座標は、フォーム送信時にフォームデータセットを構築する際に、コントロールの名前から派生した2つのエントリを送信し、名前に".x"および".y"を追加し、座標のそれぞれのxおよびyコンポーネントが追加されます。
すべての現在のエンジンでサポートされています。
画像はsrc属性によって指定されます。src
属性は存在しなければならず、空でなく、スペースで囲まれている可能性のある有効なURLを含まなければなりません。これにより、ページやスクリプトがない、インタラクティブでない、オプションでアニメーションされた画像リソースを参照します。
次のいずれかのイベントが発生したとき
input
要素のtype
属性が最初に画像ボタン状態に設定されたとき(おそらく要素が最初に作成されたとき)、およびsrc
属性が存在する場合
input
要素のtype
属性が画像ボタン状態に戻され、src属性が存在し、その値が最後にtype属性が画像ボタン状態であったとき以来変更された場合
input
要素のtype
属性が画像ボタン状態であり、src属性が設定または変更された場合
ユーザーエージェントが画像をサポートできない場合、または画像のサポートが無効になっている場合、またはユーザーエージェントが画像をオンデマンドでのみ取得する場合、またはsrc属性の値が空文字列である場合を除き、次の手順を実行します:
要素のsrc属性の値を、要素のノードドキュメントに対してURLをエンコーディングパースした結果としてurlとします。
urlが失敗の場合、戻ります。
requestは、新しいリクエストであり、URLがurlで、クライアントが要素のノードドキュメントの関連設定オブジェクトであり、デスティネーションが"image"で、イニシエータータイプが"input"で、クレデンシャルモードが"include"であり、URLクレデンシャルフラグが設定されているものとします。
Fetch requestを使用し、processResponseEndOfBodyを次のステップに設定します レスポンス responseに基づいて:
ダウンロードが成功し、画像が利用可能である場合、要素タスクをキューに入れ、input要素でloadイベントを発火します。
それ以外の場合、リモートサーバーからの応答がない場合、または取得が完了しても画像が無効またはサポートされていない場合は、要素タスクをキューに入れinput要素でerrorイベントを発火します。
画像の取得は、要素のloadイベントを遅延させなければなりません。ノードドキュメントがタスクをキューに入れ、リソースが取得された後(以下に定義)に実行されるまで。
画像がネットワークエラーなく正常に取得され、画像のタイプがサポートされているタイプであり、そのタイプの有効な画像である場合、画像は利用可能と見なされます。画像が完全にダウンロードされる前にこれが真である場合、画像が取得されている間にキューに入れられた各タスクは、画像の表示を適切に更新する必要があります。
ユーザーエージェントは、画像のタイプを決定するために画像スニッフィングルールを適用する必要があります。画像の関連するContent-Typeヘッダーが公式なタイプを提供します。これらのルールが適用されない場合、画像のタイプは画像の関連するContent-Typeヘッダーによって与えられるタイプでなければなりません。
ユーザーエージェントは、input要素に対して非画像リソースをサポートしてはなりません。ユーザーエージェントは画像リソースに埋め込まれた実行可能コードを実行してはなりません。ユーザーエージェントは、マルチページリソースの最初のページのみを表示しなければなりません。ユーザーエージェントはリソースがインタラクティブに動作することを許可してはなりませんが、リソース内のアニメーションを尊重する必要があります。
すべての現在のエンジンでサポートされています。
alt属性は、画像を使用できないユーザーやユーザーエージェントに対してボタンのテキストラベルを提供します。alt属性は必須であり、画像が利用できない場合に相当するボタンに適切なラベルを与える非空の文字列を含んでいなければなりません。
もしsrc属性が設定されており、画像が利用可能で、ユーザーエージェントがその画像を表示するように設定されている場合、要素は制御を表し、座標を選択するための制御を行います。その場合、要素が可変であれば、ユーザーエージェントはユーザーがこの座標を選択できるようにする必要があります。
それ以外の場合、要素は送信ボタンを表し、そのラベルはalt属性の値によって与えられます。
要素のeventに対する入力アクティベーションの動作は次のとおりです:
要素にフォームの所有者がいない場合、終了します。
ユーザーが座標を明示的に選択して制御をアクティベートした場合、要素の選択された座標をその座標に設定します。
これは上記の条件下でのみ可能です。このとき、要素はそのような座標を選択するための制御を表します。しかし、その場合でも、ユーザーが座標を明示的に選択せずに制御をアクティベートすることがあります。
要素のフォームを送信し、eventのユーザーのナビゲーション関与が設定されている場合、要素からフォームの所有者を送信します。
要素の選択された座標は、x成分とy成分からなります。初期状態では(0, 0)です。この座標は、要素の画像の端に対する位置を表し、座標空間ではxの正の方向が右に、yの正の方向が下に向かっています。
x成分は、xが範囲−(borderleft+paddingleft) ≤ x ≤ width+borderright+paddingright内にある有効な整数でなければなりません。ここで、widthは画像の描画された幅、borderleftは画像の左側の境界線の幅、paddingleftは画像の左側のパディングの幅、borderrightは画像の右側の境界線の幅、paddingrightは画像の右側のパディングの幅です。すべての寸法はCSSピクセルで指定されます。
y成分は、yが範囲−(bordertop+paddingtop) ≤ y ≤ height+borderbottom+paddingbottom内にある有効な整数でなければなりません。ここで、heightは画像の描画された高さ、bordertopは画像の上側の境界線の幅、paddingtopは画像の上側のパディングの幅、borderbottomは画像の下側の境界線の幅、paddingbottomは画像の下側のパディングの幅です。すべての寸法はCSSピクセルで指定されます。
境界線やパディングがない場合、その幅はCSSピクセルでゼロです。
formaction、
formenctype、
formmethod、
formnovalidate、
およびformtarget属性は、フォーム送信用の属性です。
image.width [ = value ]
image.height [ = value ]
これらの属性は画像の実際の描画寸法を返します。寸法が不明な場合は0を返します。
これらは設定可能で、対応するコンテンツ属性を変更するために使用できます。
次の一般的なinput要素のコンテンツ属性とIDL属性が要素に適用されます:
alt、
formaction、
formenctype、
formmethod、
formnovalidate、
formtarget、
height、
popovertarget、
popovertargetaction、
src、
およびwidthコンテンツ属性;
valueIDL属性。
次のコンテンツ属性は指定されてはならず、適用されません:
accept、
autocomplete、
checked、
dirname、
list、
max、
maxlength、
min、
minlength、
multiple、
pattern、
placeholder、
readonly、
required、
size、
およびstep。
要素のvalue属性は省略する必要があります。
次のIDL属性およびメソッドは、要素に適用されません:
checked、
files、
list、
selectionStart、
selectionEnd、
selectionDirection、
valueAsDate、
およびvalueAsNumberIDL属性;
select()、
setRangeText()、
setSelectionRange()、
stepDown()、
およびstepUp()メソッド。
この状態の動作の多くの側面は、img要素の動作と類似しています。読者はそのセクションを読むことを推奨します。同じ要件がより詳細に説明されています。
次のフォームを例にとります:
< form action = "process.cgi" >
< input type = image src = map.png name = where alt = "場所リストを表示" >
</ form >
ユーザーが画像の座標(127,40)をクリックした場合、フォーム送信に使用されるURLは"process.cgi?where.x=127&where.y=40"になります。
(この例では、地図が表示されないユーザーには、「場所リストを表示」というラベルの付いたボタンが表示され、ボタンをクリックすると地図の代わりに選択可能な場所のリストが表示されると仮定します。)
type=reset)すべての現在のエンジンでサポートされています。
input要素のtype属性がリセットボタン状態である場合、このセクションのルールが適用されます。
input要素は、アクティブ化されるとフォームをリセットするボタンを表します。要素にvalue属性がある場合、ボタンのラベルはその属性の値でなければなりません。そうでない場合、"リセット"などを意味する実装依存の文字列でなければなりません。この要素はボタンです。
デフォルトのラベルは実装依存であり、通常、ボタンの幅はラベルに依存するため、ボタンの幅は指紋可能な情報のビットをリークする可能性があります。これらのビットは、ユーザーエージェントの識別およびユーザーのロケールに強く関連している可能性が高いです。
要素の入力アクティベーション動作は次のとおりです:
制約検証: 要素は制約検証から除外されています。
valueIDL属性は、この要素に適用され、デフォルトモードで動作します。
次の一般的なinput要素のコンテンツ属性が要素に適用されます:
popovertargetおよびpopovertargetaction。
次のコンテンツ属性は指定されてはならず、要素に適用されません:
accept、
alt、
autocomplete、
checked、
dirname、
formaction、
formenctype、
formmethod、
formnovalidate、
formtarget、
height、
list、
max、
maxlength、
min、
minlength、
multiple、
pattern、
placeholder、
readonly、
required、
size、
src、
step、
およびwidth。
次のIDL属性およびメソッドは要素に適用されません:
checked、
files、
list、
selectionStart、
selectionEnd、
selectionDirection、
valueAsDate、
およびvalueAsNumberIDL属性;
select()、
setRangeText()、
setSelectionRange()、
stepDown()、
およびstepUp()メソッド。
type=button)すべての現在のエンジンでサポートされています。
input要素のtype属性がボタン状態である場合、このセクションのルールが適用されます。
input要素は、デフォルトの動作を持たないボタンを表します。ボタンのラベルはvalue属性に指定する必要がありますが、空の文字列でもかまいません。要素にvalue属性がある場合、ボタンのラベルはその属性の値でなければなりません。そうでない場合、ラベルは空の文字列でなければなりません。この要素はボタンです。
要素には入力アクティベーション動作はありません。
制約検証: 要素は制約検証から除外されています。
valueIDL属性は、この要素に適用され、デフォルトモードで動作します。
次の一般的なinput要素のコンテンツ属性が要素に適用されます:
popovertargetおよびpopovertargetaction。
次のコンテンツ属性は指定されてはならず、要素に適用されません:
accept、
alt、
autocomplete、
checked、
dirname、
formaction、
formenctype、
formmethod、
formnovalidate、
formtarget、
height、
list、
max、
maxlength、
min、
minlength、
multiple、
pattern、
placeholder、
readonly、
required、
size、
src、
step、およびwidth。
次のIDL属性およびメソッドは要素に適用されません:
checked、
files、
list、
selectionStart、
selectionEnd、
selectionDirection、
valueAsDate、
およびvalueAsNumberIDL属性;
select()、
setRangeText()、
setSelectionRange()、
stepDown()、
およびstepUp()メソッド。
このセクションは規範的ではありません。
ユーザーに表示される日付、時刻、および数値のコントロールの形式は、フォーム送信に使用される形式とは無関係です。
ブラウザは、日付、時刻、および数値をページのロケールに従って、またはユーザーの優先するロケールに従って表示するユーザーインターフェースを使用することが推奨されます。ページのロケールを使用することで、ページで提供されるデータとの一貫性が確保されます。
たとえば、アメリカ英語のページが02/03にCirque De Soleilのショーがあると主張しているのに、ブラウザが英国英語のロケールを使用するように設定されている場合、チケット購入の日付ピッカーに03/02としか表示されないと、ユーザーは混乱するでしょう。ページのロケールを使用することで、少なくとも日付がどこでも同じ形式で表示されるようになります。(もちろん、ユーザーが1か月遅れて到着するリスクは依然としてありますが、文化的な違いについてはできることには限界があります...)
input要素の属性これらの属性は、input要素のtype属性が、その属性が適用されると定義された状態である場合にのみ、適用されます。属性がinput要素に適用されない場合、ユーザーエージェントは、以下の要件や定義にかかわらず、その属性を無視しなければなりません。
maxlengthおよびminlength属性すべての現在のエンジンでサポートされています。
すべての現在のエンジンでサポートされています。
すべての現在のエンジンでサポートされています。
すべての現在のエンジンでサポートされています。
すべての現在のエンジンでサポートされています。
maxlength属性は、適用されると、フォームコントロールmaxlength属性です。
すべての現在のエンジンでサポートされています。
minlength属性は、適用されると、フォームコントロールminlength属性です。
input要素に最大許容値長がある場合、要素のvalue属性の値の長さは、要素の最大許容値長以下でなければなりません。
次の抜粋は、メッセージングクライアントのテキスト入力を任意に固定された文字数に制限し、この手段による会話を簡潔に強制し、知的な議論を抑制する方法を示しています。
< label > 何をしていますか? < input name = status maxlength = 140 ></ label >
ここでは、パスワードに最小長が設定されています:
< p >< label > ユーザー名: < input name = u required ></ label >
< p >< label > パスワード: < input name = p required minlength = 12 ></ label >
size属性size属性は、ビジュアルレンダリングにおいて、ユーザーが要素の値を編集している間にユーザーエージェントが表示するべき文字数を指定します。
size属性が指定されている場合、その値は有効な非負の整数であり、ゼロより大きくなければなりません。
属性が存在する場合、その値は非負整数を解析するためのルールを使用して解析され、その結果がゼロより大きい数値である場合、ユーザーエージェントは少なくともその文字数が表示されるようにするべきです。
sizeIDL属性は、ゼロより大きい非負の数値にのみ制限され、デフォルト値は20です。
readonly属性すべての現在のエンジンでサポートされています。
すべての現在のエンジンでサポートされています。
すべての現在のエンジンでサポートされています。
属性は、ユーザーがフォームコントロールを編集できるかどうかを制御するブール属性です。指定された場合、要素は変更可能ではなくなります。readonly
制約検証: readonly属性がinput要素に指定されている場合、要素は制約検証から除外されます。
disabledとreadonlyの違いは、読み取り専用のコントロールはまだ機能するのに対し、無効化されたコントロールは有効化されるまで一般に機能しないということです。これは、要素の無効化された概念に関連する規範的な要件により、この仕様の他の箇所でより詳細に記述されています(例えば、要素のアクティベーション動作、それがフォーカス可能な領域かどうか、またはエントリリストの構築時など)。無効化されたコントロールとのユーザーインタラクションに関連する他の動作、例えばテキストが選択またはコピーできるかどうかなどは、この標準では定義されていません。
テキストコントロールのみが読み取り専用に設定でき、他のコントロール(例えばチェックボックスやボタン)では読み取り専用と無効の間に有用な区別がないため、readonly属性は適用されません。
次の例では、既存の製品識別子は変更できませんが、新しい製品(まだ識別子が入力されていない行)を表す行と一貫性を保つために、フォームの一部として表示されます。
< form action = "products.cgi" method = "post" enctype = "multipart/form-data" >
< table >
< tr > < th > 製品ID < th > 製品名 < th > 価格 < th > 操作
< tr >
< td > < input readonly = "readonly" name = "1.pid" value = "H412" >
< td > < input required = "required" name = "1.pname" value = "フロアランプUlke" >
< td > ¥< input required = "required" type = "number" min = "0" step = "0.01" name = "1.pprice" value = "49.99" >
< td > < button formnovalidate = "formnovalidate" name = "action" value = "delete:1" > 削除</ button >
< tr >
< td > < input readonly = "readonly" name = "2.pid" value = "FG28" >
< td > < input required = "required" name = "2.pname" value = "テーブルランプUlke" >
< td > ¥< input required = "required" type = "number" min = "0" step = "0.01" name = "2.pprice" value = "24.99" >
< td > < button formnovalidate = "formnovalidate" name = "action" value = "delete:2" > 削除</ button >
< tr >
< td > < input required = "required" name = "3.pid" value = "" pattern = "[A-Z0-9]+" >
< td > < input required = "required" name = "3.pname" value = "" >
< td > ¥< input required = "required" type = "number" min = "0" step = "0.01" name = "3.pprice" value = "" >
< td > < button formnovalidate = "formnovalidate" name = "action" value = "delete:3" > 削除</ button >
</ table >
< p > < button formnovalidate = "formnovalidate" name = "action" value = "add" > 追加</ button > </ p >
< p > < button name = "action" value = "update" > 保存</ button > </ p >
</ form >
required属性属性はブール属性です。指定されている場合、要素はrequired必須となります。
制約検証: 要素が必須であり、そのvalueIDL属性が適用され、モードがvalueであり、要素が変更可能であり、要素の値が空文字列である場合、要素は欠落している状態になります。
次のフォームには、メールアドレスとパスワードの2つの必須フィールドがあります。また、ユーザーがパスワードフィールドとこの3つ目のフィールドに同じパスワードを入力した場合にのみ有効と見なされる3番目のフィールドがあります。
< h1 > 新しいアカウントを作成</ h1 >
< form action = "/newaccount" method = post oninput = "up2.setCustomValidity(up2.value != up.value ? 'Passwords do not match.' : '')" >
< p >
< label for = "username" > メールアドレス:</ label >
< input id = "username" type = email required name = un >
< p >
< label for = "password1" > パスワード:</ label >
< input id = "password1" type = password required name = up >
< p >
< label for = "password2" > パスワードの確認:</ label >
< input id = "password2" type = password name = up2 >
< p >
< input type = submit value = "アカウント作成" >
</ form >
ラジオボタンの場合、required属性は、グループ内のいずれかのラジオボタンが選択されていれば満たされます。したがって、次の例では、必須としてマークされたものだけでなく、任意のラジオボタンをチェックすることができます。
< fieldset >
< legend > その映画はベクデルテストを通過しましたか?</ legend >
< p >< label >< input type = "radio" name = "bechdel" value = "no-characters" > いいえ、映画には女性キャラクターが2人もいません。</ label >
< p >< label >< input type = "radio" name = "bechdel" value = "no-names" > いいえ、女性キャラクターは互いに話をしません。</ label >
< p >< label >< input type = "radio" name = "bechdel" value = "no-topic" > いいえ、女性キャラクターが話をするときはいつも男性キャラクターについてです。</ label >
< p >< label >< input type = "radio" name = "bechdel" value = "yes" required > はい。</ label >
< p >< label >< input type = "radio" name = "bechdel" value = "unknown" > わかりません。</ label >
</ fieldset >
ラジオボタングループが必須かどうかの混乱を避けるために、著者はグループ内のすべてのラジオボタンに属性を指定することをお勧めします。一般的に、初めからチェックされているコントロールがないラジオボタングループを避けることをお勧めします。この状態はユーザーが戻ることができない状態であり、一般的に貧弱なユーザーインターフェースと見なされます。
multiple属性全ての現在のエンジンでサポートされています。
全ての現在のエンジンでサポートされています。
属性はブール属性であり、ユーザーが複数の値を指定できるかどうかを示します。
multiple
次の例は、メールクライアントの「宛先」フィールドが複数のメールアドレスを受け入れる方法を示しています。
< label > 宛先: < input type = email multiple name = to ></ label >
ユーザーがユーザー連絡先データベースに友達「スパイダーマン」(アドレス「spider@parker.example.net」)と「スカーレットウィッチ」(アドレス「scarlet@avengers.example.net」)を登録しており、sと入力した場合、ユーザーエージェントはこれら2つのメールアドレスをユーザーに提案するかもしれません。
ページは、ユーザーの連絡先データベースをサイトにリンクさせることもできます。
< label > 宛先: < input type = email multiple name = to list = contacts ></ label >
...
< datalist id = "contacts" >
< option value = "hedral@damowmow.com" >
< option value = "pillar@example.com" >
< option value = "astrophy@cute.example" >
< option value = "astronomy@science.example.org" >
</ datalist >
ユーザーがこのテキストコントロールに「bob@example.net」を入力し、次に2つ目のメールアドレスの先頭に「s」と入力し始めたとします。ユーザーエージェントは、前述の2人の友達だけでなく、datalist要素に含まれる「astrophy」や「astronomy」も表示するかもしれません。
次の例は、メールクライアントの「添付ファイル」フィールドが複数のファイルのアップロードを受け入れる方法を示しています。
< label > 添付ファイル: < input type = file multiple name = att ></ label >
pattern属性全ての現在のエンジンでサポートされています。
全ての現在のエンジンでサポートされています。
属性は、コントロールの値、またはpatternmultiple属性が適用され、設定されている場合はコントロールの値をチェックするための正規表現を指定します。
指定されている場合、属性の値はJavaScriptのPattern[+UnicodeSetsMode, +N]生成物と一致しなければなりません。
input要素のコンパイルされたパターン正規表現が存在する場合、それはJavaScriptのRegExpオブジェクトです。それは次のように決定されます:
pattern属性が指定されていない場合は、何も返しません。要素にはコンパイルされたパターン正規表現がありません。pattern属性の値とします。
v") とします。もしregexpCompletionが異常終了の場合、何も返さないでください。要素にはコンパイル済みのパターン正規表現がありません。
ユーザーエージェントは、このエラーを開発者コンソールにログとして記録し、デバッグを支援することが推奨されます。
^(?:"、pattern、そして")$"の連結したものとします。v") を返します。これらの手順の理由は、単にpattern属性の値を直接使用するのではなく、二つの理由があります。第一に、文字列に対して一致させる際に、正規表現の開始が文字列の開始に固定され、終了が文字列の終了に固定されるようにしたいからです。第二に、正規表現が独立した形で有効であることを確認したいからです。つまり、"^(?:"と")$"のアンカーで囲まれた後に初めて有効になるのではなく、最初から有効である必要があります。
RegExpオブジェクトregexpが文字列inputと一致するのは、! RegExpBuiltinExec(regexp, input)がnullでない場合です。
制約検証: 要素の値が空文字列でなく、かつ要素のmultiple属性が指定されていないか、それが指定されていてもinput要素に適用されない状態であり、要素がコンパイルされたパターン正規表現を持っているが、その正規表現が要素の値と一致しない場合、要素はパターンの不一致に苦しんでいます。
制約検証: 要素の値が空文字列でなく、かつ要素のmultiple属性が指定され、input要素に適用され、要素がコンパイルされたパターン正規表現を持っているが、その正規表現が要素の各値と一致しない場合、要素はパターンの不一致に苦しんでいます。
input要素がpattern属性を指定している場合、作成者はパターンの説明を含むtitle属性を含めるべきです。ユーザーエージェントは、この属性が存在する場合に、パターンが一致しないことをユーザーに通知する際、またはフォーカスを得た時など、適切なタイミングでこの属性の内容を使用するかもしれません。
例えば、次のスニペットがあります:
< label > 部品番号:
< input pattern = "[0-9][A-Z]{3}" name = "part" title = "部品番号は、数字1桁の後に大文字のアルファベット3文字が続きます。" /> </ label >
...は、ユーザーエージェントが次のような警告を表示する原因になる可能性があります:
部品番号は、数字1桁の後に大文字のアルファベット3文字が続きます。 このフィールドが不正な場合、フォームを送信できません。
pattern属性がコントロールに存在する場合、使用されているtitle属性は、パターンを説明するものでなければなりません。ユーザーがコントロールに入力する際に役立つ限り、追加情報を含めることもできます。そうしないと、支援技術が損なわれる可能性があります。
たとえば、title 属性にコントロールのキャプションが含まれている場合、支援技術が次のように読み上げる可能性があります: 入力されたテキストが要求されるパターンと一致しません。誕生日。これは役に立ちません。
ユーザーエージェントは、エラーが発生していない状況でもtitleを表示する場合があります(たとえば、コントロールにマウスオーバーした時のツールチップとして)。そのため、作成者はtitleの文言を、必ずしもエラーが発生したとは限らないように注意すべきです。
min属性およびmax属性全ての現在のエンジンでサポートされています。
全ての現在のエンジンでサポートされています。
いくつかのフォームコントロールには、ユーザーが提供できる値の範囲を制限する明示的な制約を適用できます。通常、そのような範囲は線形で連続的です。ただし、フォームコントロールが周期的なドメインを持つ場合、そのフォームコントロールの最も広い範囲は有限であり、作成者はその範囲内で境界をまたぐ明示的な範囲を指定できます。
具体的には、type=timeコントロールの最も広い範囲は、深夜から深夜まで(24時間)であり、作成者は連続した線形範囲(例えば、午後9時から午後11時まで)や、深夜をまたぐ非連続範囲(例えば、午後11時から午前1時まで)を設定できます。
min属性およびmax属性は、その要素に対して許可される値の範囲を示します。
それらの構文は、type属性の現在の状態を定義するセクションによって定義されます。
要素にmin属性があり、文字列を数値に変換するアルゴリズムをそのmin属性の値に適用した結果が数値である場合、その数値がその要素の最小値です。それ以外の場合、type属性の現在の状態がデフォルトの最小値を定義している場合、それが最小値です。それ以外の場合、要素には最小値はありません。
要素にmax属性があり、文字列を数値に変換するアルゴリズムをそのmax属性の値に適用した結果が数値である場合、その数値がその要素の最大値です。それ以外の場合、type属性の現在の状態がデフォルトの最大値を定義している場合、それが最大値です。それ以外の場合、要素には最大値はありません。
要素が周期的なドメインを持っていない場合、max属性の値(最大値)は、min属性の値(その最小値)よりも小さくてはなりません。
周期的なドメインを持たない要素が、最小値よりも小さい最大値を持っている場合、その要素が値を持っている限り、それはアンダーフローに苦しんでいるか、オーバーフローに苦しんでいる可能性があります。
要素が逆転した範囲を持つのは、それが周期的なドメインを持ち、その最大値がその最小値よりも小さい場合です。
要素が範囲制限を持つのは、定義された最小値または定義された最大値を持っている場合です。
制約検証: 要素が最小値を持ち、逆転した範囲を持たない場合、要素の値によって得られた数値が最小値より小さい場合、要素はアンダーフローに苦しんでいます。
制約検証: 要素が最大値を持ち、逆転した範囲を持たない場合、要素の値によって得られた数値が最大値を超える場合、要素はオーバーフローに苦しんでいます。
制約検証: 要素が逆転した範囲を持っている場合、要素の値によって得られた数値が最大値を超え、かつ最小値よりも小さい場合、その要素は同時にアンダーフローとオーバーフローに苦しんでいます。
以下の日付コントロールは、1980年代以前の日付に入力を制限します:
< input name = bday type = date max = "1979-12-31" >
以下の数値コントロールは、ゼロより大きい整数に入力を制限します:
< input name = quantity required = "" type = "number" min = "1" value = "1" >
以下の時間コントロールは、午後9時から午前6時の間に発生する分に入力を制限し、デフォルトは午前0時です:
< input name = "sleepStart" type = time min = "21:00" max = "06:00" step = "60" value = "00:00" >
step属性全ての現在のエンジンでサポートされています。
step属性は、許容される値を制限することで、期待される(および必要な)値または値の粒度を示します。type属性の現在の状態を定義するセクションも、以下で説明されるように、属性の処理に使用されるデフォルトのステップ、ステップのスケールファクター、および場合によってはデフォルトのステップベースを定義します。
step属性が指定されている場合、その値は、ゼロより大きい数に解析される、有効な浮動小数点数であるか、anyという文字列のASCII 大文字小文字を区別しない一致でなければなりません。
属性は次のように要素の許容される値のステップを提供します:
属性が適用されない場合、許容される値のステップはありません。
それ以外の場合、属性が存在しない場合、許容される値のステップはデフォルトのステップにステップのスケールファクターを乗じたものです。
それ以外の場合、属性の値がanyという文字列のASCII
大文字小文字を区別しない一致である場合、許容される値のステップはありません。
それ以外の場合、浮動小数点数値の解析規則を属性の値に適用したときにエラー、ゼロ、またはゼロ未満の数が返された場合、許容される値のステップはデフォルトのステップにステップのスケールファクターを乗じたものです。
それ以外の場合、浮動小数点数値の解析規則を属性の値に適用したときに返された数にステップのスケールファクターを乗じたものが許容される値のステップです。
ステップベースは、次のアルゴリズムによって返される値です:
要素にmin属性があり、そのmin属性の値に文字列を数値に変換するアルゴリズムを適用した結果がエラーでない場合、その結果を返します。
要素にvalue属性があり、そのvalue属性の値に文字列を数値に変換するアルゴリズムを適用した結果がエラーでない場合、その結果を返します。
この要素に対してデフォルトのステップベースが定義されている場合、その値を返します。
ゼロを返します。
制約検証: 要素に許容される値のステップがあり、要素の値に文字列を数値に変換するアルゴリズムを適用した結果が数値であり、その数値からステップベースを引いたものが許容される値のステップの整数倍でない場合、要素はステップの不一致に苦しんでいます。
次の範囲コントロールは、0から1の範囲内で256のステップを受け付けます:
< input name = opacity type = range min = 0 max = 1 step = 0.00392156863 >
次のコントロールは、日中の任意の時刻を任意の精度で選択できます(例:1000分の1秒単位の精度やそれ以上):
< input name = favtime type = time step = any >
通常、時間コントロールの精度は1分単位に制限されています。
list 属性すべての現在のエンジンでサポートされています。
list
属性は、ユーザーに提案する事前定義されたオプションをリストする要素を識別するために使用されます。
存在する場合、その値は同じツリー内のdatalist要素のIDでなければなりません。
提案ソース要素は、list属性の値と等しいIDを持つ、ツリー内でツリー順において最初の要素です。その要素がdatalist要素である場合に限ります。list属性が存在しない場合、またはそのIDを持つ要素が存在しない場合、または最初の要素がdatalist要素でない場合、提案ソース要素は存在しません。
提案ソース要素が存在する場合、ユーザーエージェントがユーザーに値を編集させているとき、ユーザーエージェントは、提案ソース要素で表される提案を、使用されているコントロールの種類に適した方法でユーザーに提供する必要があります。 適切であれば、ユーザーエージェントは、提案のラベルと値を使用して、ユーザーに提案を識別させるべきです。
提案が多い場合、提案ソース要素で表される提案をフィルタリングし、最も関連性の高いものだけを含めることが推奨されます(例:ユーザーの現在の入力に基づいて)。 明確な閾値は定義されていませんが、リストを4〜7つの値に制限するのが合理的です。 ユーザーの入力に基づいてフィルタリングする場合、ユーザーエージェントは、提案のラベルおよび値内を検索して一致を探すべきです。 ユーザーエージェントは、入力の変動が一致プロセスにどのように影響するかを考慮すべきです。異なるキーボードや入力特定のメカニズムによって引き起こされる異なるUnicodeコードポイントシーケンスが一致プロセスを妨げないように、Unicode正規化を適用すべきです。 大文字小文字の違いは無視するべきで、これは言語特有の大文字小文字のマッピングを必要とする場合があります。 これらの例については、World Wide Webの文字モデル:文字列の一致を参照してください。 ユーザーエージェントは他の一致機能も提供する場合があります:たとえば、異なる形式の仮名を互いに一致させる(または漢字に一致させる)、アクセントを無視する、スペル補正を適用するなどです。 [CHARMODNORM]
このテキストフィールドでは、JavaScript関数の種類を選択できます。
< input type = "text" list = "function-types" >
< datalist id = "function-types" >
< option value = "function" > function</ option >
< option value = "async function" > async function</ option >
< option value = "function*" > generator function</ option >
< option value = "=>" > arrow function</ option >
< option value = "async =>" > async arrow function</ option >
< option value = "async function*" > async generator function</ option >
</ datalist >
上記の提案に従うユーザーエージェントでは、ラベルおよび値の両方が表示されます:
次に、「arrow」または「=>」と入力すると、「arrow function」および「async arrow function」というラベルのエントリにリストが絞り込まれます。「generator」または「*」と入力すると、「generator function」および「async generator function」というラベルのエントリにリストが絞り込まれます。
これまで通り、ユーザーエージェントは、特定の要件やユーザーの状況に応じて適切なユーザーインターフェイスの決定を自由に行うことができます。しかし、この分野はこれまで、実装者、Web開発者、およびユーザーの間で混乱を招いてきたため、上記に「すべき」という提案を提供しています。
ユーザーが提案を選択した場合の処理方法は、要素が単一の値のみを受け入れるコントロールであるか、複数の値を受け入れるかどうかによって異なります:
multiple属性が指定されていない場合、またはmultiple属性が適用されない場合
ユーザーが提案を選択したとき、input要素の値は、ユーザーがその値を書いたかのように、選択した提案の値に設定されなければなりません。
type属性がEmail状態にあり、要素にmultiple属性が指定されている場合
ユーザーが提案を選択したとき、ユーザーエージェントは、新しいエントリをinput要素の値に追加するか、既存のエントリを選択した提案の値に変更する必要があります。どちらの動作を適用するかは、実装定義の方法で行われます。
list属性が適用されない場合、提案ソース要素は存在しません。
このURLフィールドでは、いくつかの提案が表示されます。
< label > ホームページ: < input name = hp type = url list = hpurls ></ label >
< datalist id = hpurls >
< option value = "https://www.google.com/" label = "Google" >
< option value = "https://www.reddit.com/" label = "Reddit" >
</ datalist >
ユーザーの履歴から他のURLが表示されることもあります。これはユーザーエージェント次第です。
この例は、オートコンプリートリスト機能を使用しながらも、レガシーユーザーエージェントで適切にデグレードするフォームを設計する方法を示しています。
オートコンプリートリストが単なる補助であり、コンテンツにとって重要でない場合は、単に子要素optionを持つdatalist要素を使用するだけで十分です。
レガシーユーザーエージェントでこれらの値が表示されないようにするには、それらをインラインではなく、value属性内に配置する必要があります。
< p >
< label >
品種を入力してください:
< input type = "text" name = "breed" list = "breeds" >
< datalist id = "breeds" >
< option value = "アビシニアン" >
< option value = "アルパカ" >
<!-- ... -->
</ datalist >
</ label >
</ p >
しかし、レガシーユーザーエージェントで値を表示する必要がある場合は、フォールバックコンテンツをdatalist要素内に配置することができます。以下のように:
< p >
< label >
品種を入力してください:
< input type = "text" name = "breed" list = "breeds" >
</ label >
< datalist id = "breeds" >
< label >
またはリストから選択してください:
< select name = "breed" >
< option value = "" > (選択なし)
< option > アビシニアン
< option > アルパカ
<!-- ... -->
</ select >
</ label >
</ datalist >
</ p >
フォールバックコンテンツは、datalistをサポートしていないユーザーエージェントでのみ表示されます。
一方、オプションは、datalist要素の子でなくても、すべてのユーザーエージェントで検出されます。
option要素がdatalistで使用されている場合、それがselectedされていると、デフォルトでレガシーユーザーエージェントによって選択されます(select要素に影響を与えるためです)が、それはinput要素には影響を与えません。datalistをサポートしているユーザーエージェントでは効果がありません。
placeholder
属性すべての現行エンジンでサポートされています。
Element/input#attr-placeholder
すべての現行エンジンでサポートされています。
placeholder
属性は、コントロールに値が入力されていないときにユーザーのデータ入力を支援するための短いヒント(単語や短いフレーズ)を表します。ヒントは、サンプル値や期待されるフォーマットの簡単な説明である場合があります。この属性が指定されている場合、その値にはU+000A
LINE FEED(LF)またはU+000D CARRIAGE RETURN(CR)文字を含めてはいけません。
placeholder
属性は、labelの代替として使用すべきではありません。より長いヒントやその他の助言テキストには、title属性の方が適しています。
これらのメカニズムは非常に似ていますが、微妙に異なります。コントロールのlabelによって提供されるヒントは常に表示されます。placeholder属性によって提供される短いヒントは、ユーザーが値を入力する前に表示されます。そして、title属性のヒントは、ユーザーがさらなるヘルプを求めたときに表示されます。
ユーザーエージェントは、このヒントをユーザーに提示すべきです。このとき、要素の値が空文字列であり、特にコントロールがフォーカスされていない場合には、改行を除去した後に提示することが推奨されます。
通常、ユーザーエージェントがコントロールがフォーカスされているときにこのヒントを表示しない場合でも、autofocus属性の結果としてコントロールがフォーカスされた場合は、このヒントを表示するべきです。これは、その場合、ユーザーがフォーカスする前にコントロールを確認する機会を持たないためです。
以下は、placeholder属性を使用したメール設定ユーザーインターフェースの例です:
< fieldset >
< legend > メールアカウント</ legend >
< p >< label > 名前: < input type = "text" name = "fullname" placeholder = "山田 太郎" ></ label ></ p >
< p >< label > アドレス: < input type = "email" name = "address" placeholder = "taro@example.com" ></ label ></ p >
< p >< label > パスワード: < input type = "password" name = "password" ></ label ></ p >
< p >< label > 説明: < input type = "text" name = "desc" placeholder = "私のメールアカウント" ></ label ></ p >
</ fieldset >
コントロールのコンテンツの方向性とプレースホルダーの方向性が異なる場合、Unicodeの双方向アルゴリズムの書式設定文字を属性値に使用できます:
< input name = t1 type = tel placeholder = " ‫ رقم الهاتف 1 ‮ " >
< input name = t2 type = tel placeholder = " ‫ رقم الهاتف 2 ‮ " >
少しわかりやすくするために、同じ例をインラインのアラビア語の代わりに数値文字参照を使用して示します:
< input name = t1 type = tel placeholder = " ‫ رقم الهاتف 1 ‮ " >
< input name = t2 type = tel placeholder = " ‫ رقم الهاتف 2 ‮ " >
input 要素APIinput.value [ = value ]
フォームコントロールの現在の値を返します。
値を変更するために設定することができます。
ファイルアップロードコントロールの場合、空文字列以外の値に設定すると、"InvalidStateError" DOMExceptionがスローされます。
input.checked [ = value ]
フォームコントロールの現在のチェック状態を返します。
チェック状態を変更するために設定することができます。
input.files [ = files ]
すべての現行エンジンでサポートされています。
すべての現行エンジンでサポートされています。
フォームコントロールの選択されたファイルをリストしたFileListオブジェクトを返します。
コントロールがファイルコントロールでない場合は null を返します。
設定すると、フォームコントロールの選択されたファイルを変更できます。たとえば、ドラッグ&ドロップ操作の結果として。
input.valueAsDate [ = value ]
フォームコントロールの値を表すDateオブジェクトを返します(該当する場合)。そうでない場合は
null を返します。
値を変更するために設定することができます。
コントロールが日付または時刻に基づくものでない場合、"InvalidStateError" DOMExceptionをスローします。
input.valueAsNumber [ = value ]
フォームコントロールの値を表す数値を返します(該当する場合)。そうでない場合は NaN を返します。
値を変更するために設定することができます。これを NaN に設定すると、基礎となる値が空文字列に設定されます。
コントロールが日付または時刻に基づくものでないか、数値でない場合、"InvalidStateError" DOMExceptionをスローします。
input.stepUp([ n ])
input.stepDown([ n ])
フォームコントロールの値を、step属性で与えられた値にnを掛けた値だけ変更します。nのデフォルト値は
1 です。
コントロールが日付または時刻に基づくものでないか、数値でない場合、またはstep属性の値が"any"の場合、"InvalidStateError" DOMExceptionをスローします。
input.list
datalist属性で示される要素を返します。
input.showPicker()
適用可能なピッカーUIがあれば表示し、ユーザーが値を選択できるようにします。(指定されたコントロールに対してピッカーUIが実装されていない場合、このメソッドは何もしません。)
フォームコントロールが変更可能でない場合、"InvalidStateError" DOMExceptionをスローします。
一時的なユーザーアクティベーションなしで呼び出された場合、"NotAllowedError" DOMExceptionをスローします。
フォームコントロールがファイルアップロード状態またはカラー状態でない限り、クロスオリジンのiframe内にある場合、"SecurityError" DOMExceptionをスローします。
取得時には、要素の現在のvalueを返します。
設定時には次の手順を行います:
oldValueを要素のvalueとします。
要素のvalueを新しい値に設定します。
要素のダーティ値フラグをtrueに設定します。
要素の値のサニタイズアルゴリズムを、 そのtype属性の現在の状態が定義している場合に実行します。
要素のvalue(値のサニタイズアルゴリズムを適用した後)がoldValueと異なり、
要素にテキストエントリカーソルの位置がある場合は、
テキストエントリカーソルの位置をテキストコントロールの終わりに移動し、
選択されているテキストを選択解除し、選択方向を"none"にリセットします。
取得時には、要素にvalueコンテンツ属性がある場合はその属性の値を返し、そうでない場合は空の文字列を返します。
設定時には、要素のvalueコンテンツ属性の値を新しい値に設定します。
取得時には、要素にvalueコンテンツ属性がある場合はその属性の値を返し、そうでない場合は"on"という文字列を返します。
設定時には、要素のvalueコンテンツ属性の値を新しい値に設定します。
取得時には、"C:\fakepath\"という文字列に、選択されたファイルのリストの最初のファイル名を続けて返し、リストが空の場合は空の文字列を返します。
設定時に新しい値が空の文字列であれば、選択されたファイルのリストを空にします。それ以外の場合は、
"InvalidStateError"
DOMExceptionをスローします。
この "fakepath" の要件は歴史的な悲しい事故です。詳しくはファイルアップロード状態セクションの例を参照してください。
ファイル名のリストにはパスコンポーネントが含まれていないため、"\fakepath\"がパスコンポーネントと誤解されることはありません。
checked
IDL属性は、スクリプトがcheckednessを操作するために使用される
input要素です。
取得時には、要素の現在のcheckednessを返し、
設定時には、要素のcheckednessを新しい値に設定し、
要素のdirty
checkedness flagをtrueに設定しなければなりません。
files
IDL属性は、スクリプトが要素の選択されたファイルにアクセスするために使用されます。
取得時に、IDL属性が適用される場合は、現在の選択されたファイルを表す
FileListオブジェクトを返さなければなりません。
同じオブジェクトは、選択されたファイルのリストが変更されるまで返され続けなければなりません。
IDL属性が適用されない場合は、代わりにnullを返さなければなりません。
[FILEAPI]
設定時には、以下の手順を実行する必要があります:
valueAsDate
IDL属性は、要素の値を、日付として解釈したものを表します。
取得時に、valueAsDate属性が適用されない場合、
その状態に定義されているように、input要素のtype属性の現在の状態が、
nullを返します。そうでない場合は、その状態に定義されている文字列からDateオブジェクトへの変換アルゴリズムを実行し、
そのアルゴリズムがDateオブジェクトを返した場合は、それを返し、
それ以外の場合はnullを返します。
設定時に、valueAsDate属性が適用されない場合、
その状態に定義されているように、input要素のtype属性の現在の状態に対して、
"InvalidStateError"
DOMExceptionをスローします。
そうでない場合、新しい値がnullでなく、Dateオブジェクトでない場合は、TypeError例外をスローします。
そうでない場合、新しい値がnullであるか、NaN時間値を表すDateオブジェクトである場合は、
要素の値を空の文字列に設定します。
それ以外の場合は、新しい値に対してその状態に定義されている日付オブジェクトを文字列に変換するアルゴリズムを実行し、
要素の値を生成された文字列に設定します。
valueAsNumber
IDL属性は、要素の値を、数値として解釈したものを表します。
取得時に、valueAsNumber属性が適用されない場合、
その状態に定義されているように、input要素のtype属性の現在の状態が、
Not-a-Number (NaN) 値を返します。そうでない場合は、その状態に定義されている文字列から数値への変換アルゴリズムを実行し、
そのアルゴリズムが数値を返した場合はそれを返し、それ以外の場合はNot-a-Number (NaN) 値を返します。
設定時に、新しい値が無限である場合は、TypeError例外をスローします。
そうでない場合、valueAsNumber属性が適用されない場合は、
input要素の現在の状態に対して、
"InvalidStateError"
DOMExceptionをスローします。
そうでない場合、新しい値がNot-a-Number (NaN) 値である場合は、要素の値を空の文字列に設定します。
そうでない場合は、新しい値に対してその状態に定義されている数値を文字列に変換するアルゴリズムを実行し、
要素の値を生成された文字列に設定します。
stepDown(n)
およびstepUp(n)メソッドは、
呼び出された際に次のアルゴリズムを実行しなければなりません:
stepDown()およびstepUp()メソッドが適用されない場合、
その状態に定義されているように、input要素のtype属性の現在の状態が、
"InvalidStateError"
DOMExceptionをスローします。
要素に許可された値のステップがない場合は、"InvalidStateError"
DOMExceptionをスローします。
要素に最小値および最大値があり、 その最小値以上であり、 その最大値以下である値がない場合、 その値をステップ基準から引いたときに許可された値のステップの整数倍となり、 その値がなければ終了します。
文字列から数値への変換アルゴリズムを実行し、 要素の値を取得してエラーが発生しなかった場合は、 valueをそのアルゴリズムの結果に設定します。そうでない場合は、valueをゼロに設定します。
valueBeforeSteppingをvalueに設定します。
valueをステップ基準から引いた値が許可された値のステップの整数倍でない場合は、
valueを次のように設定します。
その値がstepDown()メソッドで呼び出された場合は、
value未満の最も近い値に設定し、そうでない場合はそれよりも大きい値に設定します。
それ以外の場合、valueをステップ基準から引いた値が、 許可された値のステップの整数倍である場合:
nを引数として設定します。
deltaをnに許可された値のステップを掛けた値に設定します。
stepDown()メソッドが呼び出された場合は、
deltaを否定します。
valueにdeltaを加えた結果を設定します。
要素に最小値があり、valueがその最小値より小さい場合、valueを、ステップベースから引いたときに許容される値のステップの整数倍であり、かつminimum以上である最小の値に設定します。
要素に最大値があり、valueがその最大値より大きい場合、valueを、ステップベースから引いたときに許容される値のステップの整数倍であり、かつmaximum以下である最大の値に設定します。
stepDown()メソッドが呼び出され、
valueがvalueBeforeSteppingより大きい場合、またはstepUp()メソッドが呼び出され、
valueがvalueBeforeSteppingより小さい場合は、終了します。
value as stringを次のアルゴリズムを実行して取得しなければなりません:
数値を文字列に変換するアルゴリズムを実行し、
input要素のtype属性の現在の状態に基づいて、
valueに設定します。
要素の値をvalue as stringに設定します。
listIDL属性は、現在の提案元要素を返すか、なければnullを返す必要があります。
すべての現在のエンジンでサポートされています。
HTMLInputElementのshowPicker()およびHTMLSelectElementのshowPicker()メソッドのステップは次の通りです:
thisが変更可能でない場合、"InvalidStateError" DOMExceptionをスローします。
thisの関連する設定オブジェクトのオリジンが同一オリジンでない場合、またはthisが関連する設定オブジェクトのトップレベルオリジンと異なる場合で、thisがselect要素であるか、thisのtype属性がファイルアップロード状態やカラー状態でない場合、"SecurityError" DOMExceptionをスローします。
ファイルおよびカラー入力は、歴史的理由によりこのチェックから免除されています。これらの入力の入力アクティベーション動作は、そのピッカーも表示し、オリジンチェックにより保護されることはありませんでした。
thisの関連するグローバルオブジェクトが一時的アクティベーションを持たない場合、"NotAllowedError"DOMExceptionをスローします。
thisがselect要素であり、かつthisがレンダリングされていない場合、"NotSupportedError"DOMExceptionをスローします。
適用可能であればピッカーを表示をthisに対して行います。
input要素またはselect要素elementに対して適用可能であればピッカーを表示するには:
elementの関連するグローバルオブジェクトが一時的アクティベーションを持たない場合は、終了します。
elementが変更可能でない場合は、終了します。
elementの関連するグローバルオブジェクトに対してユーザーアクティベーションを消費します。
elementがinput要素であり、かつそのtype属性がファイルアップロード状態である場合、次のステップを並行して実行します:
任意で、このアルゴリズムの以前の実行が終了するまで待機します。
ユーザーにファイルの指定を求めるプロンプトを表示します。elementにmultiple属性が設定されていない場合、選択されるファイルは1つだけでなければなりません。それ以外の場合、任意の数が選択される可能性があります。ファイルはファイルシステムから取得するか、ユーザーのデバイスに接続されているカメラで撮影した写真のようにその場で作成されることがあります。
ユーザーが選択を行うまで待機します。
ユーザーが選択を変更せずにプロンプトを閉じた場合は、elementに対して要素タスクをキューに追加し、ユーザーインタラクションタスクのソースに従って、elementでバブル属性がtrueに初期化されたイベント発火を行います。
それ以外の場合、elementのファイル選択を更新します。
すべてのユーザーインターフェース仕様と同様に、ユーザーエージェントはこれらの要件を解釈する方法にかなりの自由があります。上記のテキストは、ユーザーがプロンプトを閉じるか、選択を変更するかのどちらかであり、必ず一方が真であることを示唆しています。しかし、これらの可能性を具体的なユーザーインターフェース要素にどのようにマッピングするかは、標準によって強制されません。たとえば、ユーザーエージェントは、以前にファイルが選択されていた場合に「キャンセル」ボタンをクリックすることを、選択をゼロファイルに変更する選択と解釈し、inputおよびchangeイベントを発火することができます。または、選択を変更せずにプロンプトを閉じる解釈として、cancelイベントを発火することもできます。同様に、再選択が選択の変更としてカウントされるか、または変更されていないとカウントされるかは、ユーザーエージェントに依存します。
それ以外の場合、ユーザーエージェントは通常どおり、elementの制御とユーザーが対話する際に、適切なユーザーインターフェースを表示する必要があります。(そのようなUIがelementに適用されない場合、このステップは何も行いません。)
そのようなユーザーインターフェースが表示される場合、それはelementのtype属性状態に基づいた、仕様の関連部分に記載されている要件を尊重しなければなりません。(たとえば、さまざまなセクションで、結果となる値文字列に関する制限が記述されています。)
このステップは、副次的な効果を持つことがあります。たとえば、このアルゴリズムによって以前に表示された他のピッカーを閉じるなどです。(ファイル選択ピッカーが閉じられる場合、前述のとおり、それはinputおよびchangeイベント、またはcancelイベントのいずれかを発火します。)
執筆時点では、通常のブラウザ実装は以下のピッカーUIを表示します:
input要素で、そのtype属性がファイルアップロード状態にある場合(ただし、これらはこのステップではなく、特別なケースとして扱われます);
select要素。
ただし、このステップの意図は、いかなるピッカーUIの実装もトリガーすることです。たとえば、ユーザーエージェントがパスワード状態のためのパスワードピッカーUIを実装した場合、このメソッドはパスワード入力で呼び出されたときにそのピッカーUIを表示することが期待されます。
input
イベントおよびchange イベントが適用される場合(これは、inputコントロールのうち、ボタンおよびtype属性が状態のもの以外が対象です)、これらのイベントは、ユーザーがコントロールと対話したことを示すために発火します。
input
イベントは、ユーザーがコントロールのデータを変更するたびに発火します。change
イベントは、値が確定されたとき(コントロールにとってそれが意味を持つ場合)や、コントロールがフォーカスを失ったときに発火します。すべてのケースで、inputイベントが対応するchangeイベント(もしあれば)より先に発生します。
input要素に定義された入力
活性化動作がある場合、これらのイベントが適用される場合のイベント発行ルールは、type属性の状態を定義する上記のセクションで指定されています。(これは、inputコントロールがチェックボックス状態、ラジオボタン状態、またはファイルアップロード状態のtype属性を持つ場合に適用されます。)
入力活性化動作が定義されていないが、これらのイベントが適用される要素であり、ユーザーインターフェースが対話的な操作と明示的な確定アクションの両方を含む場合、ユーザーが要素の値を変更するとき、ユーザーエージェントは、input要素に対して要素タスクをキューに入れる必要があります。そして、イベントを発火し、inputという名前のイベントを、input要素に対して発火します。このとき、bubbles属性とcomposed属性はtrueに設定されます。そして、ユーザーが変更を確定するたびに、ユーザーエージェントはinput要素に対して要素タスクをキューに入れる必要があります。
対話的な操作と確定アクションの両方を含むユーザーインターフェースの例として、スライダーを使用するレンジコントロールが挙げられます。ユーザーがポインティングデバイスを使用してコントロールのノブをドラッグしている間、inputイベントは位置が変わるたびに発生しますが、changeイベントはユーザーがノブを離して特定の値を確定したときにのみ発生します。
入力活性化動作が定義されていないが、これらのイベントが適用される要素であり、ユーザーインターフェースが明示的な確定アクションを含むが、中間操作を含まない場合、ユーザーが要素の値を変更するたびに、ユーザーエージェントは、input要素に対して要素タスクをキューに入れる必要があります。そして、イベントを発火し、inputという名前のイベントをinput要素に対して発火します。このとき、bubbles属性とcomposed属性はtrueに設定されます。そして、input要素に対して、changeという名前のイベントを発火します。
確定アクションを含むユーザーインターフェースの例としては、1つのボタンで構成され、カラーホイールを表示するカラーコントロールが挙げられます。値がダイアログが閉じられたときにのみ変更される場合、それが明示的な確定アクションとなります。反対に、操作中に色がインタラクティブに変更される場合、確定アクションは発生しないかもしれません。
確定アクションを含む他の例としては、テキストベースのユーザー入力とドロップダウンカレンダーからのユーザー選択の両方を許可する日付コントロールがあります。テキスト入力には明示的な確定ステップが含まれないかもしれませんが、ドロップダウンカレンダーから日付を選択し、その後ドロップダウンを閉じることは確定アクションとなります。
入力活性化動作が定義されていないが、これらのイベントが適用される要素であり、ユーザーが明示的な確定アクションなしに要素の値を変更するたびに、ユーザーエージェントは、input要素に対して要素タスクをキューに入れる必要があります。そして、イベントを発火し、inputという名前のイベントを、input要素に対して発火します。このとき、bubbles属性とcomposed属性はtrueに設定されます。対応するchangeイベント(もしあれば)は、コントロールがフォーカスを失ったときに発火します。
ユーザーが要素の値を変更する例としては、ユーザーがテキストコントロールに入力する、コントロールに新しい値をペーストする、またはそのコントロール内で編集を取り消すことが挙げられます。ユーザーの一部の操作は、値の変更を引き起こしません。例として、空のテキストコントロールで「削除」キーを押す、またはクリップボードから同じテキストをコントロール内のテキストに置き換える場合が挙げられます。
キーボードを使用して操作しているユーザーがフォーカスを当てた状態でスライダー形式のレンジコントロールを操作する例も、確定ステップを伴わずに要素の値を変更する例です。
タスクが単にinputイベントを発火させるだけの場合、ユーザーエージェントは、ユーザーの操作が一段落するまでタスクをキューに入れるのを待つことができます。たとえば、ユーザーがキーを100ms押さない場合にイベントを発火させるなど、各キーストロークごとに連続して発火させるのではなく、ユーザーが一時停止したときにのみ発火させることができます。
ユーザーエージェントがユーザーに代わってinput要素の値を変更する場合(例:フォームの自動入力機能の一環として)、ユーザーエージェントは、input要素を指定して要素タスクをキューに追加し、まず対応する値を更新し、その後、inputという名前のイベントをinput要素に対して発火し、bubblesおよびcomposed属性をtrueに初期化し、その後changeという名前のイベントをinput要素に対して発火し、bubbles属性をtrueに初期化します。
これらのイベントは、スクリプトによってフォームコントロールの値が変更された場合には発火しません(これは、ユーザーがコントロールを操作した結果としてフォームコントロールの値を更新し、その後スクリプト自身の変更をフィルタリングして無限ループを避けるのを容易にするためです)。
また、ブラウザがフォームコントロールの値を、ナビゲーション中の状態復元の一部として変更した場合も、これらのイベントは発火しません。
button要素すべての現行エンジンでサポートされています。
すべての現行エンジンでサポートされています。
tabindex属性が指定された子孫が存在してはなりません。
disabled —
フォームコントロールが無効化されているかどうかform — この要素をフォーム要素と関連付けますformaction — URLをフォーム送信に使用しますformenctype — エントリリストエンコードタイプをフォーム送信に使用しますformmethod — フォーム送信に使用するバリアントformnovalidate
— フォーム送信時にフォームコントロール検証をバイパスしますformtarget — ナビゲート可能をフォーム送信のためにname — フォーム送信およびform.elements APIで使用するこの要素の名前popovertarget —
トグル、表示、非表示にするポップオーバー要素をターゲットにしますpopovertargetaction
— ターゲットとするポップオーバー要素がトグル、表示、非表示のどれになるかを示しますtype — ボタンの種類value — フォーム送信に使用される値[Exposed =Window ]
interface HTMLButtonElement : HTMLElement {
[HTMLConstructor ] constructor ();
[CEReactions ] attribute boolean disabled ;
readonly attribute HTMLFormElement ? form ;
[CEReactions ] attribute USVString formAction ;
[CEReactions ] attribute DOMString formEnctype ;
[CEReactions ] attribute DOMString formMethod ;
[CEReactions ] attribute boolean formNoValidate ;
[CEReactions ] attribute DOMString formTarget ;
[CEReactions ] attribute DOMString name ;
[CEReactions ] attribute DOMString type ;
[CEReactions ] attribute DOMString value ;
readonly attribute boolean willValidate ;
readonly attribute ValidityState validity ;
readonly attribute DOMString validationMessage ;
boolean checkValidity ();
boolean reportValidity ();
undefined setCustomValidity (DOMString error );
readonly attribute NodeList labels ;
};
HTMLButtonElement includes PopoverInvokerElement ;
button要素は、その内容によってラベル付けされるボタンを表します。
この要素はボタンです。
type属性は、ボタンがアクティブになったときの動作を制御します。これは列挙された属性で、次のキーワードと状態があります:
| キーワード | 状態 | 簡単な説明 |
|---|---|---|
submit
| 送信ボタン | フォームを送信します。 |
reset
| リセットボタン | フォームをリセットします。 |
button
| ボタン | 何もしません。 |
属性の欠落時の値のデフォルトおよび無効な値のデフォルトは、両方とも送信ボタン状態です。
type属性が送信ボタン状態にある場合、要素は特に送信ボタンです。
制約検証: type属性がリセットボタン状態またはボタン状態にある場合、要素は制約検証から除外されます。
button要素要素のeventに与えられたアクティベーション動作は次の通りです:
要素が無効の場合、終了します。
要素がフォーム所有者を持つ場合、その後、要素のtype属性の状態に応じて以下の処理を行います:
要素のフォーム所有者をeventのユーザーナビゲーション関与をユーザー関与に設定して送信します。
何もしません。
要素にポップオーバーターゲット属性のアクティベーション動作を実行します。
form属性は、button要素をそのフォーム所有者と明示的に関連付けるために使用されます。name属性は要素の名前を表します。disabled属性は、コントロールを非対話型にし、その値が送信されないようにするために使用されます。formaction、formenctype、formmethod、formnovalidate、およびformtarget属性は、フォーム送信用属性です。
formnovalidate属性を使用して、制約検証をトリガーしない送信ボタンを作成できます。
formaction、formenctype、formmethod、formnovalidate、およびformtargetは、要素のtype属性が送信ボタン状態でない場合、指定してはなりません。
value属性は、フォーム送信の目的で要素の値を提供します。要素の値は、そのvalue属性の値(存在する場合)、またはそうでない場合は空の文字列です。
ボタン(およびその値)は、そのボタン自体がフォーム送信を開始した場合にのみフォーム送信に含まれます。
valueIDL属性は、同名のコンテンツ属性を反映しなければなりません。
typeIDL属性は、同名のコンテンツ属性を反映し、既知の値のみに限定されます。
willValidate、validity、およびvalidationMessageIDL属性、およびcheckValidity()、reportValidity()、setCustomValidity()メソッドは、制約検証APIの一部です。labelsIDL属性は、この要素のラベルのリストを提供します。disabled、form、およびnameIDL属性は、この要素のフォームAPIの一部です。
次のボタンは「ヒントを表示」とラベル付けされており、アクティブにするとダイアログボックスが表示されます:
< button type = button
onclick = "alert('この15〜20分の作品はジョージ・ガーシュウィンによって作曲されました。')" >
Show hint
</ button >
select要素すべての現在のエンジンでサポートされています。
すべての現在のエンジンでサポートされています。
option、optgroup、hr、およびスクリプトサポート要素。
autocomplete —
フォームの自動入力機能のヒントdisabled —
フォームコントロールが無効かどうかform — 要素をform要素に関連付けるmultiple —
複数の値を許可するかどうかname — フォーム送信で使用する要素の名前およびform.elementsAPIでの名前required — フォーム送信に必要かどうかsize — コントロールのサイズmultiple属性またはsize属性があり、値が1より大きい場合: 作成者向け; 実装者向け。[Exposed =Window ]
interface HTMLSelectElement : HTMLElement {
[HTMLConstructor ] constructor ();
[CEReactions ] attribute DOMString autocomplete ;
[CEReactions ] attribute boolean disabled ;
readonly attribute HTMLFormElement ? form ;
[CEReactions ] attribute boolean multiple ;
[CEReactions ] attribute DOMString name ;
[CEReactions ] attribute boolean required ;
[CEReactions ] attribute unsigned long size ;
readonly attribute DOMString type ;
[SameObject ] readonly attribute HTMLOptionsCollection options ;
[CEReactions ] attribute unsigned long length ;
getter HTMLOptionElement ? item (unsigned long index );
HTMLOptionElement ? namedItem (DOMString name );
[CEReactions ] undefined add ((HTMLOptionElement or HTMLOptGroupElement ) element , optional (HTMLElement or long )? before = null );
[CEReactions ] undefined remove (); // ChildNode overload
[CEReactions ] undefined remove (long index );
[CEReactions ] setter undefined (unsigned long index , HTMLOptionElement ? option );
[SameObject ] readonly attribute HTMLCollection selectedOptions ;
attribute long selectedIndex ;
attribute DOMString value ;
readonly attribute boolean willValidate ;
readonly attribute ValidityState validity ;
readonly attribute DOMString validationMessage ;
boolean checkValidity ();
boolean reportValidity ();
undefined setCustomValidity (DOMString error );
undefined showPicker ();
readonly attribute NodeList labels ;
};
select
要素は、オプションのセットから選択するためのコントロールを表します。
すべての現在のエンジンでサポートされています。
multiple 属性は
ブール属性 です。この属性が存在する場合、select 要素は 0個以上のオプションを選択するためのコントロール です。この属性が存在しない場合、select 要素は 1つのオプションを選択するためのコントロール です。
すべての現在のエンジンでサポートされています。
size
属性は、ユーザーに表示するオプションの数を指定します。size 属性が指定されている場合、その値は 有効な非負整数
でなければなりません。
表示サイズ とは、select 要素の size 属性の値に 非負整数の解析ルール
を適用した結果です。これらのルールを適用して解析に失敗した場合、または size 属性が存在しない場合、要素の 表示サイズ は4になります。この要素の multiple
属性が存在する場合は4、存在しない場合は1です。
オプションのリスト は、select 要素のすべての option 要素の子、またはすべての
optgroup 要素の子として
select
要素の子として存在するすべての option 要素の子から構成され、ツリー順 で並べられています。
すべての現在のエンジンでサポートされています。
required 属性は
ブール属性
です。指定された場合、フォームを送信する前に値を選択する必要があります。
select 要素に required
属性が指定され、multiple
属性が指定されておらず、表示サイズ が 1 であり、最初のオプション要素の値 が空文字列で、その option 要素の親ノードが select 要素 ( optgroup 要素ではなく)
である場合、その option は
select 要素の プレースホルダーラベルオプション です。
select 要素に required
属性が指定され、multiple
属性が指定されておらず、表示サイズ が 1 である場合、その
select 要素には プレースホルダーラベルオプション
が必要です。
実際には、上記の段落で述べられた要件は、select 要素に size
属性が指定されていない場合にのみ適用されます。
制約検証: この要素に required
属性が指定されていて、option
要素のいずれにも 選択されている
設定がない場合、または唯一の option 要素の 選択状態 が プレースホルダーラベルオプション
である場合、この要素は 欠落している と見なされます。
multiple
属性が存在せず、要素が 無効
でない場合、ユーザーエージェントはユーザーが option
要素を選択できるようにする必要があります。オプションのリスト 内で、 無効 でないオプションを選択できるようにする必要があります。この option 要素が 選択される と、関連するユーザーインタラクションイベントがキューに入る前 (例: クリック
イベントの前)、ユーザーエージェントは選択された option 要素の 選択状態 を true
に設定し、その 不整合 を true
に設定し、 更新通知 を送信する必要があります。
multiple
属性が存在せず、option 要素が
オプションのリスト
にあるとき、ユーザーエージェントは、他のすべての option 要素の 選択状態 を false
に設定する必要があります。
multiple
属性が存在せず、要素の 表示サイズ
が1を超える場合、ユーザーエージェントはユーザーが option の選択状態を false
に設定する要求をすることができるようにする必要があります。この要求がユーザーエージェントに伝えられると、その option 要素の 選択状態 を false
に設定し、その 不整合 を true
に設定し、 更新通知 を送信する必要があります。
選択状態設定アルゴリズム は、select 要素
element に対して、以下の手順を実行します。
element の multiple
属性が存在せず、element の 表示サイズ が 1 であり、element の オプションのリスト に 選択状態 が
true に設定された option
要素が存在しない場合、無効
でない最初の option 要素の ツリー順 で、これを true に設定します。
element の multiple
属性が存在せず、element の オプションのリスト に option 要素が 2
つ以上存在し、それらの 選択状態 が true に設定されている場合、選択状態
を設定して、最後の option
要素を除いて他のすべての ツリー順 で false
に設定します。
option HTML 要素挿入手順
は、insertedNode を受け取ったとき、次のように実行します。
insertedNode の親が select
要素である場合、またはその親が optgroup
要素であり、その親が select
要素である場合、その 選択状態設定アルゴリズム を実行します。
option HTML 要素削除手順
は、removedNode と oldParent を受け取ったとき、次のように実行します。
oldParent が select
要素である場合、または oldParent が optgroup
要素であり、その親が select
要素である場合、その 選択状態設定アルゴリズム を実行します。
optgroup HTML 要素削除手順
は、removedNode と oldParent を受け取ったとき、次のように実行します。
oldParent が select
要素であり、removedNode が option 子要素を持つ場合、その 選択状態設定アルゴリズム を実行します。
option 要素が オプションのリスト に
リセットを要求 する場合、その 選択状態設定アルゴリズム を実行します。
multiple
属性が存在し、要素が 無効
でない場合、ユーザーエージェントはユーザーが トグル して 選択状態 を切り替えることができるようにする必要があります。この option 要素が トグルされる と (クリック、または メニューコマンド
など)、関連するユーザーインタラクションイベントがキューに入る前 (例: 関連する クリック
イベントの前)、その要素の 選択状態 を変更し、その 不整合 を true に設定し、select 更新通知 を送信する必要があります。
ユーザーエージェントが select 更新通知 を送信する場合、エレメントタスクをキュー に配置し、ユーザーインタラクションタスクのソース を指定して次のステップを実行します。
リセットアルゴリズム は select 要素
selectElement に対して実行されます。
選択状態設定アルゴリズム を実行し、 selectElement に設定します。
form 属性は、 select 要素とその フォームオーナー を明示的に関連付けるために使用されます。name 属性は、要素の名前を表します。disabled
属性は、コントロールを非インタラクティブにし、その値が送信されるのを防ぐために使用されます。autocomplete
属性は、ユーザーエージェントがオートフィルの動作を提供する方法を制御します。
select.type
すべての現在のエンジンでサポートされています。
要素にmultiple属性がある場合は
"select-multiple" を返し、それ以外の場合は "select-one" を返します。
select.options
すべての現在のエンジンでサポートされています。
オプションリストから
HTMLOptionsCollection
を返します。
select.length [ = value ]
オプションリスト内の要素の数を返します。
element = select.item(index)
すべての現在のエンジンでサポートされています。
select[index]
element = select.namedItem(name)
すべての現在のエンジンでサポートされています。
IDまたはname
nameに一致する最初の項目をオプションリストから返します。
そのIDを持つ要素が見つからない場合、nullを返します。
select.add(element [, before ])
すべての現在のエンジンでサポートされています。
elementをbeforeで指定されたノードの前に挿入します。
before引数は数値にすることができ、その場合、elementはその番号の項目の前に挿入されます。またはオプションリストから要素を指定することもでき、その場合、elementはその要素の前に挿入されます。
beforeが省略された場合、nullの場合、または範囲外の数値の場合、elementはリストの最後に追加されます。
このメソッドは、elementが挿入先の要素の祖先である場合、"HierarchyRequestError"
DOMExceptionをスローします。
select.selectedOptions
HTMLSelectElement/selectedOptions
すべての現在のエンジンでサポートされています。
選択されているオプションリストのHTMLCollection
を返します。
select.selectedIndex [ = value ]
HTMLSelectElement/selectedIndex
すべての現在のエンジンでサポートされています。
最初に選択されている項目のインデックスを返します。選択されている項目がない場合は -1 を返します。
設定することで、選択を変更できます。
select.value [ = value ]
最初に選択されている項目の値を返します。選択されている項目がない場合は空の文字列を返します。
設定することで、選択を変更できます。
select.showPicker()
selectに適用可能なピッカーUIを表示して、ユーザーが値を選択できるようにします。
selectが可変でない場合、"InvalidStateError" DOMExceptionがスローされます。
一時的なユーザーアクティベーションなしで呼び出された場合、"NotAllowedError" DOMExceptionがスローされます。
selectがクロスオリジンのiframe内にある場合、"SecurityError" DOMExceptionがスローされます。
selectが描画中でない場合、"NotSupportedError" DOMExceptionがスローされます。
type
IDL属性の取得時、multiple
属性がない場合は文字列"select-one"を返し、multiple
属性がある場合は文字列"select-multiple"を返す必要があります。
options
IDL属性は、
HTMLOptionsCollection
を返す必要があり、それはselect
ノードを基点とし、フィルターがオプションリスト内の要素に一致します。
options
コレクションは
HTMLSelectElement
オブジェクトにも反映されます。
任意の瞬間におけるサポートされているプロパティインデックスは、その瞬間にoptions属性によって返されるオブジェクトによってサポートされるインデックスです。
length
IDL属性は、コレクションにより表現されたノードの数を返す必要があります。
設定時には、options
コレクション上の同名の属性と同じように動作する必要があります。
item(index)メソッドは、options
コレクション上の同名のメソッドが、同じ引数で呼び出されたときに返す値を返す必要があります。
namedItem(name)メソッドは、options
コレクション上の同名のメソッドが、同じ引数で呼び出されたときに返す値を返す必要があります。
ユーザーエージェントが新しいインデックスプロパティの値を設定するか既存のインデックスプロパティの値を設定するとき、それはselect要素の
options
コレクション上で対応するアルゴリズムを実行しなければなりません。
同様に、add(element, before)メソッドは、その同じoptions
コレクション上の同名のメソッドのように動作する必要があります。
すべての現在のエンジンでサポートされています。
remove()
メソッドは、引数がある場合はその同じoptions
コレクション上の同名のメソッドのように動作し、引数がない場合はその祖先インターフェースであるChildNode
インターフェースを実装しているHTMLSelectElement
上の同名のメソッドのように動作する必要があります。
selectedOptions IDL属性は、
選択されている
オプションリスト内の要素に一致するフィルターを持つHTMLCollection
を返す必要があります。
selectedIndex IDL属性は、取得時に、オプションリスト内で、ツリー順序で、選択されている最初のoption要素のインデックスを返す必要があります。存在しない場合は-1を返す必要があります。
設定時に、selectedIndex
属性は、オプションリスト内のすべてのoption要素の選択状態をfalseに設定し、その後、新しい値に対応するインデックスを持つ、もしあれば、option要素の選択状態をtrueに設定し、その不完全状態をtrueに設定する必要があります。
これにより、select要素にmultiple属性がなく、表示サイズが1の場合でも、いずれの要素にも選択状態が設定されないことがあります。
value
IDL属性は、取得時に、値を返す必要があります。
オプションリスト内でツリー順序で選択状態がtrueに設定されている最初のoption要素の値を返します。存在しない場合は空文字列を返す必要があります。
設定時に、value
属性は、オプションリスト内のすべてのoption要素の選択状態をfalseに設定し、その後、新しい値に等しい値を持つ最初のoption要素に選択状態をtrueに設定し、その不完全状態をtrueに設定する必要があります。
これにより、select要素にmultiple属性がなく、表示サイズが1の場合でも、いずれの要素にも選択状態が設定されないことがあります。
multiple、required、およびsize
IDL属性は、それぞれ同名のコンテンツ属性を反映する必要があります。
sizeIDL属性にはデフォルト値が0です。
歴史的な理由により、sizeIDL属性のデフォルト値は、実際に使用されるサイズを返しません。これは、sizeコンテンツ属性がない場合、multiple属性の有無に応じて、サイズが1または4になるためです。
willValidate、
validity、およびvalidationMessage
IDL属性、およびcheckValidity()、
reportValidity()、
およびsetCustomValidity()
メソッドは、制約検証APIの一部です。labelsIDL属性は、要素のlabelのリストを提供します。disabled、form、および
nameIDL属性は、要素のフォームAPIの一部です。
次の例は、select
要素を使用して、ユーザーに一連のオプションを提供し、そこからユーザーが単一のオプションを選択できる方法を示しています。デフォルトのオプションが事前に選択されています。
< p >
< label for = "unittype" > ユニットタイプを選択:</ label >
< select id = "unittype" name = "unittype" >
< option value = "1" > マイナー </ option >
< option value = "2" > パファー </ option >
< option value = "3" selected > スナイピー </ option >
< option value = "4" > マックス </ option >
< option value = "5" > ファイヤーボット </ option >
</ select >
</ p >
デフォルトオプションがない場合、代わりにプレースホルダーを使用できます:
< select name = "unittype" required >
< option value = "" > ユニットタイプを選択 </ option >
< option value = "1" > マイナー </ option >
< option value = "2" > パファー </ option >
< option value = "3" > スナイピー </ option >
< option value = "4" > マックス </ option >
< option value = "5" > ファイヤーボット </ option >
</ select >
ここでは、ユーザーは任意の数のオプションを選択できます。デフォルトでは、5つのオプションすべてが選択されています。
< p >
< label for = "allowedunits" > このマップで有効にするユニットタイプを選択:</ label >
< select id = "allowedunits" name = "allowedunits" multiple >
< option value = "1" selected > マイナー </ option >
< option value = "2" selected > パファー </ option >
< option value = "3" selected > スナイピー </ option >
< option value = "4" selected > マックス </ option >
< option value = "5" selected > ファイヤーボット </ option >
</ select >
</ p >
時々、ユーザーは1つ以上の項目を選択する必要があります。この例では、そのようなインターフェースを示しています。
< label >
Select the songs from that you would like on your Act II Mix Tape:
< select multiple required name = "act2" >
< option value = "s1" > It Sucks to Be Me (Reprise)
< option value = "s2" > There is Life Outside Your Apartment
< option value = "s3" > The More You Ruv Someone
< option value = "s4" > Schadenfreude
< option value = "s5" > I Wish I Could Go Back to College
< option value = "s6" > The Money Song
< option value = "s7" > School for Monsters
< option value = "s8" > The Money Song (Reprise)
< option value = "s9" > There's a Fine, Fine Line (Reprise)
< option value = "s10" > What Do You Do With a B.A. in English? (Reprise)
< option value = "s11" > For Now
</ select >
</ label >
時々、セパレーターを持つことが役立つ場合があります:
< label >
Select the song to play next:
< select required name = "next" >
< option value = "sr" > Random
< hr >
< option value = "s1" > It Sucks to Be Me (Reprise)
< option value = "s2" > There is Life Outside Your Apartment
…
datalist要素
すべての現在のエンジンでサポートされています。
option要素およびスクリプトサポート要素が0個以上。
[Exposed =Window ]
interface HTMLDataListElement : HTMLElement {
[HTMLConstructor ] constructor ();
[SameObject ] readonly attribute HTMLCollection options ;
};
datalist
要素は、他のコントロールのための事前定義されたオプションを表すoption要素のセットを表します。レンダリングでは、datalist
要素は何も表さず、その子要素とともに非表示にする必要があります。
datalist
要素は、2つの方法で使用できます。最も単純な場合、datalist
要素にはoption
要素の子が含まれます。
< label >
動物:
< input name = animal list = animals >
< datalist id = animals >
< option value = "猫" >
< option value = "犬" >
</ datalist >
</ label >
より複雑な場合、datalist
要素に、datalistをサポートしない下位レベルのクライアント向けに表示するコンテンツを与えることができます。この場合、option要素はselect要素内に提供され、datalist要素内に含まれます。
< label >
Animal:
< input name = animal list = animals >
</ label >
< datalist id = animals >
< label >
or select from the list:
< select name = animal >
< option value = "" >
< option > Cat
< option > Dog
</ select >
</ label >
</ datalist >
datalist
要素は、input要素に、list属性を使用して接続されます。
option
要素は、datalist
要素の子孫であり、無効化されておらず、その値が空文字列でない文字列である場合、提案を表します。それぞれの提案には値とラベルがあります。
datalist.options
HTMLCollection
を返し、そのコレクションには、option要素が含まれます。
これらの要素はdatalist要素の子孫です。
options
IDL属性は、HTMLCollection
を返し、それはdatalist
ノードを基点とし、フィルターがoption
要素に一致します。
制約検証: 要素にdatalist
要素の祖先がある場合、それは制約検証から除外されます。
optgroup要素
すべての現在のエンジンでサポートされています。
すべての現在のエンジンでサポートされています。
select
要素の子要素として。
option
およびスクリプトサポート要素が0個以上。
optgroup
要素の終了タグは、次に別のoptgroup
要素が続く場合、または次に
hr要素が続く場合、もしくは親要素内にコンテンツが残っていない場合に省略できます。
disabled
—
フォームコントロールが無効かどうか
label —
ユーザーに表示されるラベル
[Exposed =Window ]
interface HTMLOptGroupElement : HTMLElement {
[HTMLConstructor ] constructor ();
[CEReactions ] attribute boolean disabled ;
[CEReactions ] attribute DOMString label ;
};
optgroup
要素は、共通のラベルを持つoption
要素のグループを表します。
要素のグループは、option要素で構成され、その要素はoptgroup要素の子要素です。
option
要素をselect
要素内に表示する際、ユーザーエージェントは、そのグループのoption
要素を他のoption
要素と区別して関連付けて表示する必要があります。
すべての現在のエンジンでサポートされています。
disabled
属性はboolean
属性であり、無効な
option
要素のグループを一緒に無効にするために使用できます。
label
属性は必ず指定されなければなりません。その値は、ユーザーインターフェースの目的で、グループの名前を示します。ユーザーエージェントは、この属性の値を使用して、
option
要素のグループにラベルを付ける必要があります。
disabled属性とlabel属性は、それぞれ同名のコンテンツ属性を反映しなければなりません。
optgroup
要素を選択する方法はありません。選択できるのはoption
要素のみです。
optgroup
要素は単にoption
要素のグループにラベルを提供するだけです。
以下のスニペットは、3つのコースからの一連のレッスンをselect
ドロップダウンウィジェットで提供する方法を示しています:
< form action = "courseselector.dll" method = "get" >
< p > どのコースを今日は視聴しますか?
< p >< label > コース:
< select name = "c" >
< optgroup label = "8.01 物理学 I: 古典力学" >
< option value = "8.01.1" > レクチャー01: 10の冪
< option value = "8.01.2" > レクチャー02: 1次元運動学
< option value = "8.01.3" > レクチャー03: ベクトル
< optgroup label = "8.02 電気と磁気" >
< option value = "8.02.1" > レクチャー01: 我々の世界を支えているものは何か?
< option value = "8.02.2" > レクチャー02: 電場
< option value = "8.02.3" > レクチャー03: 電気束
< optgroup label = "8.03 物理学 III: 振動と波動" >
< option value = "8.03.1" > レクチャー01: 周期的現象
< option value = "8.03.2" > レクチャー02: 拍
< option value = "8.03.3" > レクチャー03: 減衰付き強制振動
</ select >
</ label >
< p >< input type = submit value = "▶ 再生" >
</ form >
option 要素すべての最新エンジンでサポート。
すべての最新エンジンでサポート。
select 要素の子として使用する場合。
datalist
要素の子として使用する場合。
optgroup
要素の子として使用する場合。
label 属性と value 属性を持つ場合: 内容なし。
label 属性を持ち、value 属性を持たない場合: テキスト。
label 属性を持たず、datalist
要素の子でない場合: テキスト(要素間の空白は含まれません)。
label 属性を持たず、datalist
要素の子である場合: テキスト。
option 要素の 終了タグ は、option
要素が直後に続く場合、optgroup
要素が直後に続く場合、または親要素内にこれ以上コンテンツがない場合に省略可能です。
disabled —
フォームコントロールが無効かどうか
label — ユーザーが目にするラベル
selected —
オプションがデフォルトで選択されているかどうか
value — フォーム送信に使用される値
[Exposed =Window ,
LegacyFactoryFunction =Option (optional DOMString text = "", optional DOMString value , optional boolean defaultSelected = false , optional boolean selected = false )]
interface HTMLOptionElement : HTMLElement {
[HTMLConstructor ] constructor ();
[CEReactions ] attribute boolean disabled ;
readonly attribute HTMLFormElement ? form ;
[CEReactions ] attribute DOMString label ;
[CEReactions ] attribute boolean defaultSelected ;
attribute boolean selected ;
[CEReactions ] attribute DOMString value ;
[CEReactions ] attribute DOMString text ;
readonly attribute long index ;
};
option 要素は、select 要素のオプションまたは datalist
要素のサジェストリストの一部を表します。
select
要素の定義で説明されている特定の状況では、option 要素が select 要素の プレースホルダーラベルオプション
になることがあります。プレースホルダーラベルオプション は、実際のオプションを表すのではなく、select コントロールのラベルを表します。
すべての現在のエンジンでサポートされています。
disabled 属性は Boolean 属性 です。option 要素が 無効 であるかどうかは、disabled
属性が存在するかどうか、または optgroup 要素の子要素で、その
disabled
属性が存在するかどうかで決まります。
option 要素が 無効 な場合、その要素で click
イベントが発生しないようにする必要があります。これにより、タスクをキューに追加
してから、その要素に対して ユーザーインタラクションタスクソース からタスクが発生することを防ぎます。
label
属性は要素のラベルを提供します。option
要素の ラベル は、label
コンテンツ属性の値(存在し、その値が空でない場合)か、そうでない場合は、要素の text IDL 属性の値です。
label
コンテンツ属性は、指定されている場合、空であってはなりません。
value
属性は、要素の値を提供します。option
要素の 値 は、value
コンテンツ属性の値(存在する場合)か、そうでない場合は、要素の text IDL 属性の値です。
selected 属性は Boolean 属性 です。これは要素のデフォルトの 選択状態 を表します。
ダーティネス とは、option 要素の状態を示すブール値で、初期値は
false です。これは、selected
コンテンツ属性を追加または削除したときに影響を与えるかどうかを制御します。
選択状態 とは、option 要素の状態を示すブール値で、初期値は
false です。特に指定がない限り、要素が作成されたとき、その 選択状態 は selected 属性が存在する場合
true に設定されます。
option 要素の selected 属性が追加された場合、ダーティネス が false の場合は、選択状態 を true
に設定する必要があります。option 要素の
selected
属性が削除された場合、ダーティネス が false
なら、その 選択状態 を false
に設定する必要があります。
Option()
コンストラクターは、引数が3つ以下の場合、選択状態 の初期状態を上書きし、第三引数が true であっても常に false
に設定します。これにより selected
属性が設定されます。第四引数を使用して、コンストラクターを使用するときに初期の 選択状態 を明示的に設定することができます。
select 要素に multiple
属性が指定されていない場合、その子孫の option 要素には、selected
属性が設定されている要素が一つだけでなければなりません。
option 要素の インデックス は、同じ オプションリスト にある他の option
要素のうち、ツリーの順序で前にあるものの数です。option 要素が オプションリスト
に含まれていない場合、その option
要素の インデックス は 0 です。
option.selected
要素が選択されている場合は true を、そうでない場合は false を返します。
現在の状態を上書きするために設定することができます。
option.index
option.form
要素が属する form
要素を返します。存在しない場合は null を返します。
option.text
textContent
と同様ですが、スペースが圧縮され、script 要素がスキップされます。
option = new Option([ text [, value [, defaultSelected [, selected ] ] ] ])
すべての現在のエンジンでサポートされています。
新しい option
要素を返します。
text 引数は要素の内容を設定します。
value 引数は value 属性を設定します。
defaultSelected 引数は selected
属性を設定します。
selected 引数は要素が選択されているかどうかを設定します。省略された場合、defaultSelected 引数が true であっても、要素は選択されません。
disabled
IDL 属性は、同じ名前のコンテンツ属性を 反映 しなければなりません。defaultSelected IDL 属性も、selected コンテンツ属性を 反映 しなければなりません。
label IDL
属性は、取得時に label
コンテンツ属性が存在する場合はその値を返さなければならず、そうでない場合は要素の ラベル を返さなければなりません。設定時には、要素の label
コンテンツ属性を新しい値に設定しなければなりません。
value IDL
属性は、取得時には要素の 値 を返さなければならず、設定時には要素の
value
コンテンツ属性を新しい値に設定しなければなりません。
selected
IDL 属性は、取得時に要素の 選択状態 が true であれば true を返し、そうでない場合は false
を返さなければなりません。設定時には、要素の 選択状態 を新しい値に設定し、その要素の ダーティネス を true
に設定し、その後、要素に リセットを依頼 させなければなりません。
index IDL
属性は、要素の インデックス を返さなければなりません。
text IDL
属性は、取得時には、ASCII スペース文字をストリップおよび圧縮 し、ツリー順で要素のすべての Text
ノードの データ を連結した結果を返さなければならず、それらの子孫である script 要素または SVG script 要素の子孫を除外しなければなりません。
text 属性のセッターは、この要素内で指定された値で 文字列をすべて置換 しなければなりません。
form IDL
属性の動作は、option 要素が select
要素内にあるかどうかによって異なります。option 要素が親要素として select 要素を持っている場合、または
optgroup
要素を親要素として持ち、その optgroup 要素が親要素として
select 要素を持っている場合、その
form IDL 属性は、その select 要素の form IDL
属性と同じ値を返さなければなりません。そうでない場合は、null を返さなければなりません。
レガシーのファクトリー関数が提供されており、HTMLOptionElement
オブジェクトを作成するために使用されます(createElement()
のような DOM のファクトリー メソッドに加えて使用されます):Option(text, value, defaultSelected, selected)。呼び出されたとき、レガシーのファクトリー関数は以下の手順を実行する必要があります。
document を 現在のグローバル
オブジェクト の 関連付けられた
Document とします。
option を 要素を作成する
の結果とし、document、option、および HTML 名前空間 を使用します。
text が空文字列でない場合、option に Text
ノードを追加し、そのデータを text とします。
defaultSelected が true の場合は、"selected"
を使用して option に 属性値を設定 し、空の文字列を設定します。
selected が true の場合、option の 選択状態 を true に設定します。それ以外の場合は、defaultSelected が true であっても、その 選択状態 を false に設定します。
option を返します。
textarea要素すべての現在のエンジンでサポートされています。
すべての現在のエンジンでサポートされています。
autocomplete
— フォームの自動入力機能のヒント
cols — 1行あたりの最大文字数
dirname — 要素の方向性をフォーム送信で送信するために使用するフォームコントロールの名前
disabled —
フォームコントロールが無効であるかどうか
form — 要素をフォーム要素に関連付ける
maxlength
— 値の最大長さ
minlength
— 値の最小長さ
name — フォーム送信およびform.elementsAPIで使用する要素の名前
placeholder
— フォームコントロール内に表示されるユーザー向けラベル
readonly
— ユーザーが値を編集できるかどうか
required
— フォーム送信にコントロールが必要かどうか
rows — 表示する行数
wrap — フォーム送信のためにフォームコントロールの値がどのようにラップされるか
[Exposed =Window ]
interface HTMLTextAreaElement : HTMLElement {
[HTMLConstructor ] constructor ();
[CEReactions ] attribute DOMString autocomplete ;
[CEReactions ] attribute unsigned long cols ;
[CEReactions ] attribute DOMString dirName ;
[CEReactions ] attribute boolean disabled ;
readonly attribute HTMLFormElement ? form ;
[CEReactions ] attribute long maxLength ;
[CEReactions ] attribute long minLength ;
[CEReactions ] attribute DOMString name ;
[CEReactions ] attribute DOMString placeholder ;
[CEReactions ] attribute boolean readOnly ;
[CEReactions ] attribute boolean required ;
[CEReactions ] attribute unsigned long rows ;
[CEReactions ] attribute DOMString wrap ;
readonly attribute DOMString type ;
[CEReactions ] attribute DOMString defaultValue ;
attribute [LegacyNullToEmptyString ] DOMString value ;
readonly attribute unsigned long textLength ;
readonly attribute boolean willValidate ;
readonly attribute ValidityState validity ;
readonly attribute DOMString validationMessage ;
boolean checkValidity ();
boolean reportValidity ();
undefined setCustomValidity (DOMString error );
readonly attribute NodeList labels ;
undefined select ();
attribute unsigned long selectionStart ;
attribute unsigned long selectionEnd ;
attribute DOMString selectionDirection ;
undefined setRangeText (DOMString replacement );
undefined setRangeText (DOMString replacement , unsigned long start , unsigned long end , optional SelectionMode selectionMode = "preserve");
undefined setSelectionRange (unsigned long start , unsigned long end , optional DOMString direction );
};
textarea要素は、その要素の生の値のための複数行プレーンテキスト編集コントロールを表します。コントロールの内容はコントロールのデフォルト値を表します。
生の値は、textareaコントロールの初期値は空文字列でなければなりません。
この要素には、双方向アルゴリズムに関わるレンダリング要件があります。
readonly属性は、ユーザーがテキストを編集できるかどうかを制御するブール属性です。
この例では、テキストコントロールは読み取り専用としてマークされています。なぜなら、読み取り専用のファイルを表しているからです:
Filename: < code > /etc/bash.bashrc</ code >
< textarea name = "buffer" readonly >
# System-wide .bashrc file for interactive bash(1) shells.
# To enable the settings / commands in this file for login shells as well,
# this file has to be sourced in /etc/profile.
# If not running interactively, don't do anything
[ -z "$PS1" ] && return
...</ textarea >
制約のバリデーション: readonly属性がtextarea要素に指定されている場合、その要素は制約バリデーションから除外されます。
textarea要素は、変更可能である場合、無効でも、readonly属性が指定されてもいない場合。
textareaが変更可能である場合、その生の値はユーザーによって編集可能であるべきです。ユーザーエージェントは、ユーザーがテキストを編集、挿入、削除し、U+000A
LINE FEED (LF) 文字の形で改行を挿入および削除できるようにする必要があります。ユーザーが要素の生の値を変更するたびに、ユーザーエージェントは要素タスクをキューに入れる必要があり、ユーザーインタラクションタスクソースに与えられたtextarea要素にイベントを発火させ、bubblesとcomposed属性をtrueに初期化します。ユーザーエージェントは、ユーザーのインタラクションが一時的に中断されるまで、タスクをキューに入れるのを待つことができます。例えば、ユーザーが100ms間キーを押さなかった場合にイベントを発火させることができ、これにより、各キー押下のたびにイベントを連続的に発火させるのではなく、ユーザーが一時停止したときにのみイベントを発火させます。
textarea要素の汚れ値フラグは、ユーザーがコントロールとインタラクションして生の値を変更したときにtrueに設定される必要があります。
複製手順では、textarea要素の生の値と汚れ値フラグを、複製されるノードからコピーへと伝播させる必要があります。
子供が変わった時の手順では、textarea要素の汚れ値フラグがfalseである場合、その要素の生の値をその要素の子供のテキストコンテンツに設定する必要があります。
リセットアルゴリズムでは、textarea要素のユーザー有効性をfalseに設定し、汚れ値フラグをfalseに戻し、要素の生の値をその要素の子供のテキストコンテンツに設定する必要があります。
textarea要素がオープン要素のスタックからポップオフされたとき、ユーザーエージェントは要素のリセットアルゴリズムを実行する必要があります。
要素が変更可能である場合、ユーザーエージェントは要素の書字方向を左から右または右から左のいずれかに変更できるようにするべきです。ユーザーがこれを行った場合、ユーザーエージェントは次の手順を実行する必要があります:
要素のdir属性を、ユーザーが左から右の書字方向を選択した場合は"ltr"に、右から左の書字方向を選択した場合は"rtl"に設定します。
要素タスクをキューに入れる必要があり、ユーザーインタラクションタスクソースに与えられたtextarea要素にイベントを発火させる必要があります。イベント名はinputで、bubblesとcomposed属性がtrueに初期化されます。
cols属性は、1行あたりの最大文字数を指定します。cols属性が指定されている場合、その値は0より大きい有効な非負整数でなければなりません。属性値に対して非負整数の解析ルールを適用し、0より大きい数値が得られた場合、要素の文字幅はその値となります。そうでない場合は20です。
ユーザーエージェントは、要素のtextarea要素の文字幅を、ユーザーに1行あたりにサーバーが希望する文字数のヒントとして提供できます(例えば、視覚的なユーザーエージェントの場合、その幅をその文字数とすることができます)。視覚的なレンダリングでは、ユーザーエージェントはユーザーの入力をレンダリング内でラップし、各行がこの文字数を超えないようにするべきです。
rows属性は、表示する行数を指定します。rows属性が指定されている場合、その値は0より大きい有効な非負整数でなければなりません。属性値に対して非負整数の解析ルールを適用し、0より大きい数値が得られた場合、要素の文字高さはその値となります。そうでない場合は2です。
視覚的なユーザーエージェントは、コントロールの高さを文字高さによって設定するべきです。
wrap属性は、以下のキーワードと状態を持つ列挙属性です:
| キーワード | 状態 | 簡単な説明 |
|---|---|---|
soft |
ソフト | テキストは送信時にはラップされません(レンダリング中にはラップされる場合があります)。 |
hard |
ハード | テキストは、送信時にユーザーエージェントによってラップされるように改行が追加されます。 |
属性の欠落値のデフォルトと無効値のデフォルトはどちらもソフト状態です。
要素のwrap属性がハード状態にある場合、cols属性を指定する必要があります。
歴史的な理由から、要素の値は3つの異なる目的のために3つの異なる方法で正規化されます。生データの値は、最初に設定された値です。これは正規化されません。APIの値は、valueIDL属性、textLengthIDL属性、およびmaxlengthおよびminlengthコンテンツ属性で使用される値です。この値は、行区切りがU+000A
LINE FEED (LF)文字に統一されるように正規化されます。最後に、値があり、これはこの仕様のフォーム送信や他の処理モデルで使用されます。これもAPIの値と同様に正規化されますが、さらに必要に応じて、要素のwrap属性に基づいて、テキストが指定された幅で折り返されるように追加の改行が挿入されます。
要素のAPI値を取得するためのアルゴリズムは、要素の生の値を返し、改行を正規化します。
要素の値は、要素のAPI値に定義されており、テキストエリアのラッピング変換を適用します。テキストエリアのラッピング変換は、文字列に適用される次のアルゴリズムです:
要素のwrap属性がハード状態にある場合、文字列にU+000A LINE FEED (LF)
文字を挿入し、各行に最大で文字幅の文字を持つようにします。この要件の目的のために、行は文字列の開始、終了、およびU+000A
LINE FEED (LF) 文字によって区切られます。
maxlength属性はフォームコントロールのmaxlength属性です。
textarea要素が許容される最大値の長さを持つ場合、要素の子孫は次のようになります。要素の長さが、要素の許容される最大値の長さ以下でなければなりません。改行を正規化します。
minlength属性はフォームコントロールのminlength属性です。
required属性はブール属性です。指定されると、フォームを送信する前にユーザーが値を入力する必要があります。
制約のバリデーション: 要素にrequired属性が指定され、要素が変更可能であり、要素の値が空文字列である場合、その要素は欠落に苦しんでいます。
placeholder属性は、コントロールに値がない場合にユーザーのデータ入力を支援するために意図された短いヒント(単語または短いフレーズ)を表します。ヒントは、サンプル値や予想される形式の簡単な説明である場合があります。
placeholder属性は、labelの代替として使用されるべきではありません。より長いヒントや他のアドバイザリーテキストの場合は、title属性の方が適しています。
これらのメカニズムは非常に似ていますが、微妙に異なります。コントロールのlabelによって示されるヒントは常に表示されます。placeholder属性に指定された短いヒントは、ユーザーが値を入力する前に表示されます。そしてtitle属性に指定されたヒントは、ユーザーがさらにヘルプを求めたときに表示されます。
ユーザーエージェントは、このヒントをユーザーに対して、コントロールの値が空文字列であり、コントロールがフォーカスされていないときに表示するべきです(例:空の未フォーカスのコントロール内に表示する)。すべてのU+000D CARRIAGE RETURN U+000A LINE FEED文字のペア(CRLF)、およびヒント内のすべての他のU+000D CARRIAGE RETURN(CR)およびU+000A LINE FEED(LF)文字は、ヒントをレンダリングする際には改行として扱わなければなりません。
ユーザーエージェントが通常、コントロールがフォーカスされているときにこのヒントをユーザーに表示しない場合でも、autofocus属性の結果としてコントロールがフォーカスされた場合は、そのヒントを表示するべきです。なぜなら、その場合、ユーザーはコントロールをフォーカスする前に調べる機会がなかったためです。
name属性は要素の名前を表します。dirname属性は、要素の方向性がどのように送信されるかを制御します。disabled属性は、コントロールを非対話的にし、その値を送信できないようにするために使用されます。form属性は、textarea要素をそのフォーム所有者と明示的に関連付けるために使用されます。autocomplete属性は、ユーザーエージェントが自動入力動作を提供する方法を制御します。
textarea.type文字列"textarea"を返します。
textarea.value要素の現在の値を返します。
値を変更するために設定することができます。
cols、placeholder、required、rows、およびwrapIDL属性は、それぞれ同じ名前のコンテンツ属性を反映する必要があります。colsおよびrows属性は、ゼロより大きい正の数にのみ限定され、フォールバックがあります。colsIDL属性のデフォルト値は20です。rowsIDL属性のデフォルト値は2です。dirNameIDL属性は、dirnameコンテンツ属性を反映する必要があります。maxLengthIDL属性は、maxlengthコンテンツ属性を反映し、ゼロ以上の数値にのみ限定されます。minLengthIDL属性は、minlengthコンテンツ属性を反映し、ゼロ以上の数値にのみ限定されます。readOnlyIDL属性は、readonlyコンテンツ属性を反映する必要があります。
typeIDL属性は、"textarea"という値を返す必要があります。
defaultValue属性のgetterは、要素の子供のテキストコンテンツを返す必要があります。
defaultValue属性のsetterは、すべてを文字列置換し、この要素内に指定された値を設定する必要があります。
value
IDL属性は、取得時に要素のAPI値を返す必要があります。設定時には、以下の手順を実行する必要があります。
この要素のAPI値をoldAPIValueとして設定します。
この要素の生の値を新しい値に設定します。
この要素の汚れ値フラグをtrueに設定します。
新しいAPI値がoldAPIValueと異なる場合は、テキストコントロールの末尾にテキストエントリカーソル位置を移動し、選択されているテキストを選択解除し、選択方向をリセットして"none"に設定します。
textLength IDL属性は、要素の長さを返す必要があります。
willValidate、validity、およびvalidationMessageIDL属性、およびcheckValidity()、reportValidity()、およびsetCustomValidity()メソッドは、制約検証APIの一部です。ラベルIDL属性は、要素のラベルのリストを提供します。選択()、選択開始、選択終了、選択方向、範囲テキストを設定()、および選択範囲を設定()メソッドとIDL属性は、要素のテキスト選択を公開します。無効、フォーム、および名前IDL属性は、要素のフォームAPIの一部です。
ここでは、textarea要素が、フォーム内で自由形式のテキスト入力に使用される例を示します:
< p > ご意見がございましたら、お知らせください: < textarea cols = 80 name = comments ></ textarea ></ p >
コメントの最大長を指定するには、maxlength属性を使用します:
< p > 短いコメントがございましたら、お知らせください: < textarea cols = 80 name = comments maxlength = 200 ></ textarea ></ p >
デフォルト値を指定するには、要素内にテキストを含めます:
< p > ご意見がございましたら、お知らせください: < textarea cols = 80 name = comments > You rock!</ textarea ></ p >
最低限の長さを指定することもできます。ここでは、ユーザーが手紙を記入する必要があり、テンプレート(最小長より短い)が提供されていますが、フォームを送信するには不十分です:
< textarea required minlength = "500" > Dear Madam Speaker,
Regarding your letter dated ...
...
Yours Sincerely,
...</ textarea >
プレースホルダーを使用して、ユーザーに基本的な形式を示すこともできますが、明示的なテンプレートは提供しません:
< textarea placeholder = "Dear Francine,
They closed the parks this week, so we won't be able to
meet your there. Should we just have dinner?
Love,
Daddy" ></ textarea >
要素のdirname属性を指定することで、ブラウザに要素の方向性を値と一緒に送信させることができます:
< p > ご意見がございましたら、お知らせください(コメントには英語またはヘブライ語を使用できます):
< textarea cols = 80 name = comments dirname = comments.dir ></ textarea ></ p >
output要素すべての現在のエンジンでサポートされています。
すべての現在のエンジンでサポートされています。
for — 出力が計算されたコントロールを指定
form — 要素をフォーム要素に関連付けます
name — form.elementsAPIで使用する要素の名前。
[Exposed =Window ]
interface HTMLOutputElement : HTMLElement {
[HTMLConstructor ] constructor ();
[SameObject , PutForwards =value ] readonly attribute DOMTokenList htmlFor ;
readonly attribute HTMLFormElement ? form ;
[CEReactions ] attribute DOMString name ;
readonly attribute DOMString type ;
[CEReactions ] attribute DOMString defaultValue ;
[CEReactions ] attribute DOMString value ;
readonly attribute boolean willValidate ;
readonly attribute ValidityState validity ;
readonly attribute DOMString validationMessage ;
boolean checkValidity ();
boolean reportValidity ();
undefined setCustomValidity (DOMString error );
readonly attribute NodeList labels ;
};
output
要素は、アプリケーションによって実行された計算の結果、またはユーザーの操作の結果を表します。
この要素は、以前に実行された他のプログラムの出力を引用するための適切な要素であるsamp 要素と対照をなします。
すべての現在のエンジンでサポートされています。
for
コンテンツ属性は、計算結果と計算に使用された値または計算に影響を与えた要素との間に明示的な関係を作成することを可能にします。指定されている場合、for 属性には、一意のスペースで区切られたトークンの無順序集合を含む文字列が含まれている必要があります。これらのトークンのいずれも、別のトークンと同一でない必要があり、各トークンは同じツリー内の要素のIDである必要があります。
form 属性は、output 要素をそのフォーム所有者と明示的に関連付けるために使用されます。name 属性は、要素の名前を表します。output
要素は、フォームのイベントハンドラから簡単に参照できるようにフォームに関連付けられますが、フォームが送信されるときに要素自体の値は送信されません。
この要素には、デフォルト値のオーバーライド (nullまたは文字列) があります。最初はnullに設定されます。
要素のデフォルト値は、次の手順によって決定されます。
この要素のデフォルト値のオーバーライドがnullでない場合は、それを返します。
この要素の子孫テキストコンテンツを返します。
output 要素のリセットアルゴリズムは、次の手順を実行します:
この要素のデフォルト値のオーバーライドをnullに設定します。
output.value [ = value ]
要素の現在の値を返します。
設定して値を変更することができます。
output.defaultValue [ = value ]
要素の現在のデフォルト値を返します。
設定してデフォルト値を変更することができます。
output.type
"output" という文字列を返します。
value
ゲッターステップでは、この要素の子孫テキストコンテンツを返します。
value セッターステップは次のとおりです:
この要素のデフォルト値のオーバーライドをそのデフォルト値に設定します。
defaultValue ゲッターステップは、この要素のデフォルト値を返します。
defaultValue
セッターステップは次のとおりです:
もしこの要素のデフォルト値のオーバーライドがnullであれば、指定された値ですべて置換を実行し、返します。
この要素のデフォルト値のオーバーライドを指定された値に設定します。
type
ゲッターステップは、"output" を返します。
htmlFor
IDL属性は、for コンテンツ属性を反映する必要があります。
willValidate、validity、およびvalidationMessage
IDL属性、およびcheckValidity()、reportValidity()、およびsetCustomValidity()
メソッドは、制約検証APIの一部です。labels IDL属性は、要素のラベルのリストを提供します。form および name IDL属性は、要素のフォームAPIの一部です。
簡単な電卓では、計算結果を表示するために output を使用することができます:
< form onsubmit = "return false" oninput = "o.value = a.valueAsNumber + b.valueAsNumber" >
< input id = a type = number step = any > +
< input id = b type = number step = any > =
< output id = o for = "a b" ></ output >
</ form >
この例では、リモートサーバーで行われた計算の結果を受け取り次第、output 要素に表示しています:
< output id = "result" ></ output >
< script >
var primeSource = new WebSocket( 'ws://primes.example.net/' );
primeSource. onmessage = function ( event) {
document. getElementById( 'result' ). value = event. data;
}
</ script >
progress 要素現在のすべてのエンジンでサポートされています。
現在のすべてのエンジンでサポートされています。
progress
要素の子孫は存在してはならない。
value — 要素の現在の値
max — 範囲の上限
[Exposed =Window ]
インターフェイス HTMLProgressElement : HTMLElement {
[HTMLConstructor ] コンストラクター ();
[CEReactions ] 属性 double value ;
[CEReactions ] 属性 double max ;
readonly 属性 double position ;
readonly 属性 NodeList labels ;
};
progress
要素はタスクの完了進捗を表します。進捗は不確定であり、進捗が進んでいるが、タスクが完了するまでにどれだけの作業が残っているかが明確でない(例:タスクがリモートホストの応答を待っているため)か、進捗がゼロから最大までの範囲の数値であり、これまでに完了した作業の割合を示します。
現在のすべてのエンジンでサポートされています。
要素が表す現在のタスク完了を決定する属性は 2 つあります。value
属性はタスクの完了度を指定し、max
属性はタスクに必要な作業量全体を指定します。単位は任意で指定されていません。
決定的な進捗バーを作成するには、現在の進捗(0.0 から 1.0 までの数値、または max 属性が指定されている場合はその値までの数値)を持つ value 属性を追加します。不確定な進捗バーを作成するには、value 属性を削除します。
著者には、進捗がレガシーユーザーエージェントのユーザーにも利用できるように、現在の値と最大値を要素内のテキストとしてインラインに含めることをお勧めします。
これは、ある自動タスクの進捗を表示する Web アプリケーションのスニペットです:
< section >
< h2 > タスクの進捗</ h2 >
< p > 進捗: < progress id = p max = 100 >< span > 0</ span > %</ progress ></ p >
< script >
var progressBar = document. getElementById( 'p' );
function updateProgress( newValue) {
progressBar. value = newValue;
progressBar. getElementsByTagName( 'span' )[ 0 ]. textContent = newValue;
}
</ script >
</ section >
(この例のupdateProgress() メソッドは、タスクの進行に応じて実際の進捗バーを更新するために、ページ上の他のコードによって呼び出されます。)
valueおよびmax属性が存在する場合、その値は有効な浮動小数点数でなければなりません。value属性が存在する場合、その値は 0
以上で、かつmax属性の値以下(max
属性が存在しない場合は 1.0 以下)でなければなりません。max属性が存在する場合、その値は 0
より大きくなければなりません。
progress要素は、単なるゲージとして使用するには不適切です。たとえば、ディスクスペースの使用状況をprogress要素で示すのは不適切です。そのような使用ケースには、meter要素を使用できます。
ユーザーエージェントの要件:value属性が省略されている場合、進捗バーは不確定な進捗バーです。それ以外の場合、それは決定的な進捗バーです。
決定的な進捗バーであり、要素がmax属性を持っている場合、ユーザーエージェントはmax属性の値を浮動小数点数値の解析ルールに従って解析する必要があります。これがエラーにならない場合、および解析された値が
0 より大きい場合、進捗バーの最大値はその値です。そうでない場合、つまり要素にmax属性がない場合、またはそれがあっても解析がエラーとなった場合、または解析された値が
0 以下であった場合、進捗バーの最大値は 1.0
です。
決定的な進捗バーである場合、ユーザーエージェントはvalue属性の値を浮動小数点数値の解析ルールに従って解析する必要があります。これがエラーにならず、解析された値が
0 より大きい場合、進捗バーの値はその解析された値です。そうでない場合、つまりvalue属性の解析がエラーになったか、値が
0 以下であった場合、進捗バーの値は 0 です。
決定的な進捗バーである場合、現在の値は、値が最大値より大きい場合は最大値であり、そうでない場合は値です。
進捗バーを表示する際のユーザーエージェントの要件:progress要素をユーザーに表示する際、ユーザーエージェントはそれが決定的な進捗バーか不確定な進捗バーかを示すべきであり、前者の場合は、現在の値が最大値に対して相対的にどの位置にあるかを示すべきです。
progress.position
決定的な進捗バー(現在の値と最大値が既知の場合)では、現在の値を最大値で割った結果を返します。
不確定な進捗バーの場合、-1を返します。
進捗バーが不確定な進捗バーの場合、position IDL属性は-1を返さなければなりません。それ以外の場合、現在の値を最大値で割った結果を返さなければなりません。
進捗バーが不確定な進捗バーの場合、value IDL属性は取得時に0を返さなければなりません。それ以外の場合、現在の値を返さなければなりません。設定時には、与えられた値を浮動小数点数としての最良の表現に変換し、valueコンテンツ属性にその文字列を設定しなければなりません。
value
IDL属性をそのまま自身に設定すると、対応するコンテンツ属性がない場合、進捗バーは不確定な状態から進捗のない決定的な進捗バーに変更されます。
max
IDL属性は、同名のコンテンツ属性を反映し、正の数に限定されます。maxのデフォルト値は1.0です。
labels IDL属性は、この要素のlabelをリストとして提供します。
meter 要素すべての現在のエンジンでサポートされています。
すべての現在のエンジンでサポートされています。
meter要素の子孫が存在してはなりません。
value — 要素の現在の値
min — 範囲の下限
max — 範囲の上限
low — 低い範囲の上限
high — 高い範囲の下限
optimum — ゲージ内の最適値
[Exposed =Window ]
interface HTMLMeterElement : HTMLElement {
[HTMLConstructor ] constructor ();
[CEReactions ] attribute double value ;
[CEReactions ] attribute double min ;
[CEReactions ] attribute double max ;
[CEReactions ] attribute double low ;
[CEReactions ] attribute double high ;
[CEReactions ] attribute double optimum ;
readonly attribute NodeList labels ;
};
meter要素は、既知の範囲内のスカラー測定値、または分数値を表します。例えば、ディスク使用量、クエリ結果の関連性、または特定の候補者を選択した投票者の割合などです。
これはゲージとも呼ばれます。
meter要素は、進行状況(進捗バーのような)を示すために使用してはなりません。その役割には、HTMLが別のprogress要素を提供します。
meter要素は、任意の範囲のスカラー値も表しません。たとえば、既知の最大値がない限り、体重や身長を報告するためにこれを使用するのは間違いです。
この要素が表すゲージの意味を決定する6つの属性があります。
すべての現在のエンジンでサポートされています。
すべての現在のエンジンでサポートされています。
min属性は範囲の下限を指定し、max属性は上限を指定します。value属性は、ゲージが「測定された」値として示す値を指定します。
他の3つの属性は、ゲージの範囲を「低」、「中」、「高」の部分に分割し、ゲージの「最適」部分がどこかを示すために使用できます。low属性は「低」部分と見なされる範囲を指定し、high属性は「高」部分と見なされる範囲を指定します。optimum属性は「最適」位置を示します。それが「高」値より高い場合は、値が高いほど良いことを示し、それが「低」マークより低い場合は、値が低いほど良いことを示し、自然にその間にある場合は、高い値も低い値も良くないことを示します。
作成要件: value属性は指定されなければなりません。value、min、low、high、max、およびoptimum属性が存在する場合、それらの値は有効な浮動小数点数でなければなりません。
さらに、属性の値には以下の制約があります:
valueをvalue属性の数値とします。
指定されている場合、min属性をminimumとし、それ以外の場合は0とします。
指定されている場合、max属性をmaximumとし、それ以外の場合は1.0とします。
以下の不等式が適用可能な場合に成り立つ必要があります:
minimum ≤ value ≤ maximum
最小値や最大値が指定されていない場合、範囲は0から1と仮定され、その範囲内に値がなければなりません。
著者は、meter要素をサポートしないユーザーエージェントのユーザーのために、要素の内容にゲージの状態をテキストで表現することを推奨します。
マイクロデータと一緒に使用する場合、meter要素のvalue属性は、その要素の機械可読値を提供します。
以下の例は、3つのゲージがいずれも3/4満たされていることを示しています:
ストレージスペースの使用量: < meter value = 6 max = 8 > 6ブロック使用(全8ブロック中)</ meter >
投票率: < meter value = 0.75 >< img alt = "75%" src = "graph75.png" ></ meter >
チケット販売数: < meter min = "0" max = "100" value = "75" ></ meter >
次の例は、範囲を指定していないため、要素の誤った使用法です(デフォルトの最大値は1であるため、どちらのゲージも最大値として表示されます):
< p > グレープフルーツパイの半径は< meter value = 12 > 12cm</ meter > で、高さは< meter value = 2 > 2cm</ meter > です。</ p > <!-- BAD! -->
代わりに、meter要素を含めないか、他のパイと比較して次元を文脈化するために範囲を定義したmeter要素を使用します:
< p > グレープフルーツパイの半径は12cmで、高さは2cmです。</ p >
< dl >
< dt > 半径: < dd > < meter min = 0 max = 20 value = 12 > 12cm</ meter >
< dt > 高さ: < dd > < meter min = 0 max = 10 value = 2 > 2cm</ meter >
</ dl >
meter要素には、明示的に単位を指定する方法はありませんが、title属性で単位を自由形式のテキストで指定することができます。
上記の例は、単位を示すために拡張できます:
< dl >
< dt > 半径: < dd > < meter min = 0 max = 20 value = 12 title = "centimeters" > 12cm</ meter >
< dt > 高さ: < dd > < meter min = 0 max = 10 value = 2 title = "centimeters" > 2cm</ meter >
</ dl >
ユーザーエージェントの要件: ユーザーエージェントは、min、max、value、low、high、およびoptimum属性を、浮動小数点数値を解析するためのルールを使用して解析する必要があります。
ユーザーエージェントは次に、これらすべての数値を使用して、ゲージ上の6つのポイントの値を次のように取得する必要があります。(これらの評価の順序は重要です。一部の値は前の値を参照します。)
min属性が指定され、その値を解析できる場合、最小値はその値です。そうでない場合、最小値は0です。
max属性が指定され、その値を解析できる場合、候補最大値はその値です。そうでない場合、候補最大値は1.0です。
候補最大値が最小値以上の場合、最大値は候補最大値です。そうでない場合、最大値は最小値と同じです。
value属性が指定され、その値を解析できる場合、その値が候補実際値です。そうでない場合、候補実際値は0です。
候補実際値が最小値より小さい場合、実際の値は最小値です。
それ以外の場合、候補実際値が最大値より大きい場合、実際の値は最大値です。
それ以外の場合、実際の値は候補実際値です。
low属性が指定され、その値を解析できる場合、候補低境界はその値です。そうでない場合、候補低境界は最小値と同じです。
候補低境界が最小値より小さい場合、低境界は最小値です。
それ以外の場合、候補低境界が最大値より大きい場合、低境界は最大値です。
それ以外の場合、低境界は候補低境界です。
high属性が指定され、その値を解析できる場合、候補高境界はその値です。そうでない場合、候補高境界は最大値と同じです。
候補高境界が低境界より小さい場合、高境界は低境界です。
それ以外の場合、候補高境界が最大値より大きい場合、高境界は最大値です。
それ以外の場合、高境界は候補高境界です。
optimum属性が指定され、その値を解析できる場合、候補最適点はその値です。そうでない場合、候補最適点は最小値と最大値の中間点です。
候補最適点が最小値より小さい場合、最適点は最小値です。
それ以外の場合、候補最適点が最大値より大きい場合、最適点は最大値です。
それ以外の場合、最適点は候補最適点です。
これにより、以下の不等式がすべて成り立つようになります:
最小値 ≤ 実際の値 ≤ 最大値
最小値 ≤ 低境界 ≤ 高境界 ≤ 最大値
最小値 ≤ 最適点 ≤ 最大値
ゲージ領域に関するUAの要件: 最適点が低境界または高境界、またはその間のどこかにある場合、ゲージの低境界と高境界の間の領域は最適領域と見なされ、低および高の部分(ある場合)はサブ最適と見なされます。それ以外の場合、最適点が低境界より低い場合、最小値と低境界の間の領域は最適領域と見なされ、低境界から高境界までの領域はサブ最適領域と見なされ、残りの領域はさらに良くない領域と見なされます。最後に、最適点が高境界より高い場合、状況は逆転し、高境界と最大値の間の領域は最適領域と見なされ、高境界から低境界までの領域はサブ最適領域と見なされ、残りの領域はさらに良くない領域と見なされます。
ゲージの表示に関するUAの要件: ユーザーにmeter要素を表示する際に、UAは実際の値の最小値および最大値に対する相対的な位置、およびゲージの3つの領域との関係を示す必要があります。
次のマークアップ:
< h3 > Suggested groups</ h3 >
< menu >
< li >< a href = "?cmd=hsg" onclick = "hideSuggestedGroups()" > Hide suggested groups</ a ></ li >
</ menu >
< ul >
< li >
< p >< a href = "/group/comp.infosystems.www.authoring.stylesheets/view" > comp.infosystems.www.authoring.stylesheets</ a > -
< a href = "/group/comp.infosystems.www.authoring.stylesheets/subscribe" > join</ a ></ p >
< p > Group description: < strong > Layout/presentation on the WWW.</ strong ></ p >
< p > < meter value = "0.5" > Moderate activity,</ meter > Usenet, 618 subscribers</ p >
</ li >
</ li >
< p >< a href = "/group/netscape.public.mozilla.xpinstall/view" > netscape.public.mozilla.xpinstall</ a > -
< a href = "/group/netscape.public.mozilla.xpinstall/subscribe" > join</ a ></ p >
< p > Group description: < strong > Mozilla XPInstall discussion.</ strong ></ p >
< p > < meter value = "0.25" > Low activity,</ meter > Usenet, 22 subscribers</ p >
</ li >
</ li >
< p >< a href = "/group/mozilla.dev.general/view" > mozilla.dev.general</ a > -
< a href = "/group/mozilla.dev.general/subscribe" > join</ a ></ p >
< p > < meter value = "0.25" > Low activity,</ meter > Usenet, 66 subscribers</ p >
</ li >
</ ul >
次のようにレンダリングされる可能性があります:
ユーザーエージェントは、title属性の値と他の属性の値を組み合わせて、コンテキストに敏感なヘルプや実際の値の詳細を提供するインラインテキストを提供することができます。
例えば、次のスニペット:
< meter min = 0 max = 60 value = 23.2 title = seconds ></ meter >
...は、ユーザーエージェントが次のようなツールチップを表示する可能性があります。「値:60中23.2。」という1行と、「秒」という2行目。
valueIDL属性は、取得時に実際の値を返さなければなりません。設定時に、指定された値は浮動小数点数としての数の最適な表現に変換され、valueコンテンツ属性にその文字列が設定されなければなりません。
minIDL属性は、取得時に最小値を返さなければなりません。設定時に、指定された値は浮動小数点数としての数の最適な表現に変換され、minコンテンツ属性にその文字列が設定されなければなりません。
maxIDL属性は、取得時に最大値を返さなければなりません。設定時に、指定された値は浮動小数点数としての数の最適な表現に変換され、maxコンテンツ属性にその文字列が設定されなければなりません。
lowIDL属性は、取得時に低境界を返さなければなりません。設定時に、指定された値は浮動小数点数としての数の最適な表現に変換され、lowコンテンツ属性にその文字列が設定されなければなりません。
highIDL属性は、取得時に高境界を返さなければなりません。設定時に、指定された値は浮動小数点数としての数の最適な表現に変換され、highコンテンツ属性にその文字列が設定されなければなりません。
optimumIDL属性は、取得時に最適値を返さなければなりません。設定時に、指定された値は浮動小数点数としての数の最適な表現に変換され、optimumコンテンツ属性にその文字列が設定されなければなりません。
labelsIDL属性は、要素のlabelのリストを提供します。
次の例は、ゲージがローカライズされたテキストや整形されたテキストにフォールバックする方法を示しています。
< p > ディスク使用量: < meter min = 0 value = 170261928 max = 233257824 > 170 261 928バイト使用済み(全233 257 824バイト中)</ meter ></ p >
fieldset
要素
すべての現在のエンジンでサポートされています。
すべての現在のエンジンでサポートされています。
legend
要素、続いてフローコンテンツ.
disabled
—
後続のフォームコントロール(legend内を除く)が無効であるかどうか
form — この要素をform要素に関連付ける
name — APIにおいてform.elementsで使用されるこの要素の名前
[Exposed =Window ]
interface HTMLFieldSetElement : HTMLElement {
[HTMLConstructor ] constructor ();
[CEReactions ] attribute boolean disabled ;
readonly attribute HTMLFormElement ? form ;
[CEReactions ] attribute DOMString name ;
readonly attribute DOMString type ;
[SameObject ] readonly attribute HTMLCollection elements ;
readonly attribute boolean willValidate ;
[SameObject ] readonly attribute ValidityState validity ;
readonly attribute DOMString validationMessage ;
boolean checkValidity ();
boolean reportValidity ();
undefined setCustomValidity (DOMString error );
};
fieldset
要素は、フォームコントロール(またはその他のコンテンツ)をグループ化し、オプションでキャプションを付けるためのものです。キャプションは、このfieldset要素の最初のlegend要素によって提供されます(存在する場合)。残りの子孫はグループを形成します。
Element/fieldset#attr-disabled
すべての現在のエンジンでサポートされています。
disabled属性が指定されると、fieldset要素のすべてのフォームコントロールの子孫(ただし、legend要素の子孫を除く)が無効になります。
fieldset要素は、次の条件のいずれかを満たす場合に無効なフィールドセットとなります:
form属性は、このfieldset要素をそのフォーム所有者に明示的に関連付けるために使用されます。name属性は要素の名前を表します。
fieldset.type
文字列 "fieldset" を返します。
fieldset.elements
要素内のフォームコントロールのHTMLCollectionを返します。
disabledIDL属性は、同名のコンテンツ属性を反映しなければなりません。
typeIDL属性は、文字列 "fieldset" を返さなければなりません。
elementsIDL属性は、HTMLCollectionを返し、fieldset要素をルートとし、そのフィルターはリストされた要素に一致します。
willValidate、validity、validationMessage属性、およびcheckValidity()、reportValidity()、setCustomValidity()メソッドは、制約検証APIの一部です。formおよびnameIDL属性は、要素のフォームAPIの一部です。
この例では、関連するコントロールのセットをグループ化するためにfieldset要素が使用されています:
< fieldset >
< legend > 表示</ legend >
< p >< label >< input type = radio name = c value = 0 checked > 白地に黒</ label >
< p >< label >< input type = radio name = c value = 1 > 黒地に白</ label >
< p >< label >< input type = checkbox name = g > グレースケールを使用</ label >
< p >< label > コントラストを強化 < input type = range name = e list = contrast min = 0 max = 100 value = 0 step = 1 ></ label >
< datalist id = contrast >
< option label = Normal value = 0 >
< option label = Maximum value = 100 >
</ datalist >
</ fieldset >
次のスニペットは、legend 内のチェックボックスが fieldset の有効・無効を制御するフィールドセットを示しています。fieldset の内容は、2つの必須テキストコントロールとオプションの年/月コントロールで構成されています。
< fieldset name = "clubfields" disabled >
< legend > < label >
< input type = checkbox name = club onchange = "form.clubfields.disabled = !checked" >
クラブカードを使用する
</ label > </ legend >
< p >< label > カードの名前: < input name = clubname required ></ label ></ p >
< p >< label > カード番号: < input name = clubnum required pattern = "[-0-9]+" ></ label ></ p >
< p >< label > 有効期限: < input name = clubexp type = month ></ label ></ p >
</ fieldset >
また、fieldset要素をネストすることもできます。次の例では、前述の例を拡張し、それを示しています:
< fieldset name = "clubfields" disabled >
< legend > < label >
< input type = checkbox name = club onchange = "form.clubfields.disabled = !checked" >
クラブカードを使用する
</ label > </ legend >
< p >< label > カードの名前: < input name = clubname required ></ label ></ p >
< fieldset name = "numfields" >
< legend > < label >
< input type = radio checked name = clubtype onchange = "form.numfields.disabled = !checked" >
私のカードには数字が書かれています
</ label > </ legend >
< p >< label > カード番号: < input name = clubnum required pattern = "[-0-9]+" ></ label ></ p >
</ fieldset >
< fieldset name = "letfields" disabled >
< legend > < label >
< input type = radio name = clubtype onchange = "form.letfields.disabled = !checked" >
私のカードには文字が書かれています
</ label > </ legend >
< p >< label > カードコード: < input name = clublet required pattern = "[A-Za-z]+" ></ label ></ p >
</ fieldset >
</ fieldset >
この例では、外側の「クラブカードを使用する」チェックボックスがチェックされていない場合、外側のfieldset内のすべて、つまり2つのネストされたfieldsetの
legend 内の2つのラジオボタンを含め、すべてが無効になります。ただし、チェックボックスがチェックされている場合、ラジオボタンの両方が有効になり、どちらの内側のfieldsetを有効にするかを選択できるようになります。
この例では、legend要素がグループ化をラベル付けし、ネストされた見出し要素がドキュメントのアウトラインにグループ化を表示する方法を示しています:
< fieldset >
< legend > < h2 >
どの方法でご連絡するのが最適ですか?
</ h2 > </ legend >
< p >< label > < input type = radio checked name = contact_pref > 電話</ label > </ p >
< p >< label > < input type = radio name = contact_pref > メール
</ label > </ p >
</ p >< label > < input type = radio name = contact_pref > テキスト
</ label > </ p >
</ fieldset >
legend 要素すべての現在のエンジンでサポートされています。
すべての現在のエンジンでサポートされています。
fieldset 要素の最初の子として使用
[Exposed =Window ]
interface HTMLLegendElement : HTMLElement {
[HTMLConstructor ] constructor ();
readonly attribute HTMLFormElement ? form ;
// also has obsolete members
};
legend 要素は、legend 要素の親である fieldset
要素の残りの内容のキャプションを表します(もし存在する場合)。
legend.form
要素の form
要素を返します(もし存在する場合)、それ以外は null を返します。
form IDL
属性の動作は、legend 要素が fieldset
要素内にあるかどうかによって異なります。legend 要素が親として fieldset 要素を持つ場合、その
form IDL 属性は、その form IDL 属性と同じ値を返す必要があります。それ以外の場合は null
を返す必要があります。
ほとんどのフォームコントロールには、値とチェック状態があります。(後者は input
要素でのみ使用されます。)これらは、ユーザーがコントロールとどのようにやり取りするかを説明するために使用されます。
コントロールの 値 はその内部状態です。そのため、ユーザーの現在の入力と一致しない場合があります。
例えば、ユーザーが数字を期待している 数値フィールド
に「three」という単語を入力した場合、ユーザーの入力は「three」という文字列ですが、コントロールの 値 は変更されません。また、ユーザーが「
awesome@example.com」(先頭に空白がある)というメールアドレスを メールフィールド に入力した場合、ユーザーの入力は「
awesome@example.com」という文字列になりますが、ブラウザのメールフィールドのUIでは、これが「awesome@example.com」(先頭の空白なし)という 値 に変換されることがあります。
input および textarea 要素には、汚れた値フラグがあります。これは、値 とデフォルト値の間のやり取りを追跡するために使用されます。このフラグが false の場合、値 はデフォルト値を反映します。true
の場合、デフォルト値は無視されます。
input、textarea、および
select 要素には、ユーザー有効性というブール値があります。これは初期設定では false に設定されています。
input 要素の multiple
属性における制約検証の挙動を定義するために、input 要素には別々に定義された
複数の値 も持つことができます。
maxlength および minlength 属性の挙動、ならびに
textarea
要素に特有の他のAPIを定義するために、値
を持つすべてのフォームコントロールは、API値を取得するためのアルゴリズムも持っています。このアルゴリズムのデフォルトは、単にコントロールの 値 を返すことです。
select 要素には 値 がなく、代わりに option 要素の 選択状態 が使用されます。
フォームコントロールは変更可能と指定することができます。
これは、この仕様で定義される要件や定義を通じて、ユーザーがフォームコントロールの値やチェック状態を変更できるか、またはコントロールが自動的に事前入力されるかどうかを判断するものです。
フォーム関連要素は、フォーム要素と関係を持つことができ、これをその要素のフォーム所有者と呼びます。フォーム関連要素がフォーム要素と関連付けられていない場合、そのフォーム所有者はnullとされます。
フォーム関連要素には、関連するパーサー挿入フラグがあります。
すべての現行エンジンでサポートされています。
すべての現行エンジンでサポートされています。
フォーム関連要素は、デフォルトでは最も近い祖先のフォーム要素と関連付けられます(以下で説明されます)が、リスト化された要素である場合は、form属性を指定することでこれを上書きすることができます。
この機能は、ネストされたフォーム要素のサポートがないことを補うために、著者が利用できるようにします。
リスト化されたリスト化されたフォーム関連要素にform属性が指定されている場合、その属性の値は、その要素のIDでなければなりません。その要素のツリー内にあるフォーム要素のIDです。
このセクションのルールは、準拠する文書やツリーにはネストされたフォーム要素が含まれないため複雑です。しかし、DOM操作を行うスクリプトを使用して、このようなネストされた要素を持つツリーを生成することは十分に可能です。また、歴史的な理由から、HTMLパーサーのルールによって、フォーム関連要素が祖先ではないフォーム要素と関連付けられることがあり、それも複雑さを増しています。
フォーム関連要素が作成されると、そのフォーム所有者はnull(所有者なし)に初期化される必要があります。
フォーム関連要素をフォームと関連付ける場合、そのフォーム所有者はそのフォームに設定される必要があります。
リスト化されたリスト化されたフォーム関連要素のform属性が設定、変更、または削除された場合、ユーザーエージェントはその要素のフォーム所有者をリセットしなければなりません。
リスト化されたリスト化されたフォーム関連要素がform属性を持ち、そのツリー内の任意の要素のIDが変更された場合、ユーザーエージェントはそのフォーム所有者をリセットしなければなりません。
リスト化されたリスト化されたフォーム関連要素がform属性を持ち、IDを持つ要素が文書に挿入された、または文書から削除された場合、ユーザーエージェントはそのフォーム所有者をリセットしなければなりません。
フォーム所有者は、HTML Standardの挿入ステップおよび削除ステップによってもリセットされます。
フォーム関連要素 element のフォームオーナーをリセットするには:
element のパーサー挿入フラグを解除します。
以下のすべての条件が真である場合:
element のフォームオーナーがnullでない;
その場合は何もしません。
element のフォームオーナーをnullに設定します。
それ以外の場合、element が祖先にフォーム要素を持つ場合、そのelementを最も近いフォーム要素に関連付けます。
以下の非準拠スニペットでは
...
< form id = "a" >
< div id = "b" ></ div >
</ form >
< script >
document. getElementById( 'b' ). innerHTML =
'<table><tr><td></form><form id="c"><input id="d"></table>' +
'<input id="e">' ;
</ script >
...
"d" のフォームオーナーは内側のネストされたフォーム "c" ですが、"e" のフォームオーナーは外側のフォーム "a" になります。
これは次のように起こります: 最初に、"e" ノードはHTMLパーサーで "c" に関連付けられます。次に、innerHTMLアルゴリズムがノードを一時的なドキュメントから
"b" 要素に移動させます。この時点で、ノードはその祖先チェーンの変更を認識し、そのためパーサーによって行われたすべての "魔法のような" 関連付けが通常の祖先関連付けにリセットされます。
ただし、この例はコンテンツモデルに違反しており、フォーム要素をネストすることは不正です。また、</form>タグに解析エラーがあります。
element.form
すべての最新のエンジンでサポートされています。
すべての最新のエンジンでサポートされています。
要素のフォームオーナーを返します。
フォームオーナーが存在しない場合は null を返します。
リスト化された フォーム関連要素
は、フォーム関連カスタム要素 を除き、
form IDL属性を持ち、取得時にその要素のフォームオーナーを返すか、存在しない場合はnullを返します。
すべての最新のエンジンでサポートされています。
フォーム関連カスタム要素には
form IDL属性がありません。
代わりに、その
ElementInternals
オブジェクトには、form IDL属性があります。取得時に、"NotSupportedError" DOMExceptionを投げなければならず、ターゲット要素がフォーム関連カスタム要素でない場合は投げる必要があります。そうでない場合は、その要素のフォームオーナーを返すか、存在しない場合はnullを返します。
name
属性
すべての現在のエンジンでサポートされています。
name コンテンツ属性は、フォームコントロールの名前を指定し、
フォーム送信
および form
要素の elements
オブジェクトで使用されます。属性が指定されている場合、その値は空文字列や isindex であってはなりません。
多くのユーザーエージェントは、isindex
という名前の最初のフォーム内のテキストコントロールに対して、特別なサポートを実装していました。この仕様では以前、このサポートに関連するユーザーエージェントの要件を定義していました。しかし、その後いくつかのユーザーエージェントがその特別なサポートを廃止し、それに関連する要件もこの仕様から削除されました。そのため、レガシーユーザーエージェントでの問題のある再解釈を避けるために、isindex
という名前はもはや許可されていません。
isindex 以外の、name
の任意の非空値は許可されています。ASCII
大文字と小文字を区別しない 名前 _charset_ は特別です。
コントロールの名前として使用され、value
属性が指定されていない場合、送信中に value
属性に送信文字エンコーディングが自動的に設定されます。
name IDL属性は、反映する必要があります。name
コンテンツ属性を。
DOMのクロブリングはセキュリティ問題の一般的な原因です。組み込みのフォームプロパティ名を name
コンテンツ属性に使用することは避けてください。
この例では、input
要素が組み込みの method
プロパティを上書きします:
let form = document. createElement( "form" );
let input = document. createElement( "input" );
form. appendChild( input);
form. method; // => "get"
input. name = "method" ; // DOMのクロブリングがここで発生
form. method === input; // => true
入力名が組み込みフォームプロパティより優先されるため、JavaScriptリファレンス
form.method は、組み込みの method
プロパティではなく、「method」と名付けられた input
要素を指します。
dirname
属性すべての現在のエンジンでサポートされています。
dirname
フォームコントロール要素の属性は、要素の方向性
を送信し、フォーム送信中に
この値を含むコントロールの名前を指定します。このような属性が指定されている場合、その値は空文字列であってはなりません。
この例では、フォームにテキストコントロールと送信ボタンが含まれています:
< form action = "addcomment.cgi" method = post >
< p >< label > コメント: < input type = text name = "comment" dirname = "comment.dir" required ></ label ></ p >
< p >< button name = "mode" type = submit value = "add" > コメントを投稿</ button ></ p >
</ form >
ユーザーがフォームを送信すると、ユーザーエージェントは "comment"、"comment.dir"、"mode" の3つのフィールドを含めます。したがって、ユーザーが "Hello" と入力すると、送信ボディは次のようになります:
comment=Hello&comment.dir=ltr&mode=add
ユーザーが手動で右から左への書字方向に切り替えて "مرحبا" と入力すると、送信ボディは次のようになる可能性があります:
comment=%D9%85%D8%B1%D8%AD%D8%A8%D8%A7&comment.dir=rtl&mode=add
maxlength
属性
フォームコントロールの
maxlength 属性は、dirty value flag
によって制御され、ユーザーが入力できる文字数の制限を宣言します。文字数は長さで測定され、textarea
要素の場合は、すべての改行が1文字に正規化されます(CRLFペアではなく)。
要素にフォームコントロールの
maxlength 属性が指定されている場合、この属性の値は有効な非負整数でなければなりません。属性が指定されていて、その値に非負整数を解析するためのルール
を適用すると数値になる場合、その数値が要素の許容される最大値の長さになります。属性が省略されている場合や、その値を解析してエラーが発生した場合、許容される最大値の長さ
はありません。
制約検証: 要素に許容される最大値の長さ があり、そのdirty value flag がtrueで、値 が最後にユーザーの編集によって変更された場合(スクリプトによる変更ではなく)、その要素の長さが要素の許容される最大値の長さ を超える場合、要素は長すぎる状態になります。
ユーザーエージェントは、要素のAPI値 を、要素の長さが許容される最大値の長さ を超える値に設定することを防ぐ場合があります。
textarea
要素の場合、API値
と値
は異なります。特に、改行の正規化が適用されてから、許容される最大値の長さ
がチェックされます(textarea
の折り返し変換は適用されません)。
minlength
属性
フォームコントロールの
minlength 属性は、dirty value flag
によって制御され、ユーザーが入力できる文字数の下限を宣言します。「文字数」は長さで測定され、textarea
要素の場合、すべての改行が1文字に正規化されます(CRLFペアではなく)。
minlength
属性はrequired 属性を暗示しません。フォームコントロールにrequired 属性がない場合、値は省略可能です。minlength
属性は、ユーザーが値を入力した時点でのみ有効になります。空文字列を許可しない場合は、required 属性も設定する必要があります。
要素にフォームコントロールの
minlength 属性が指定されている場合、この属性の値は有効な非負整数でなければなりません。属性が指定されていて、その値に非負整数を解析するためのルール
を適用すると数値になる場合、その数値が要素の許容される最小値の長さになります。属性が省略されている場合や、その値を解析してエラーが発生した場合、許容される最小値の長さはありません。
要素に許容される最大値の長さ と許容される最小値の長さが両方指定されている場合、許容される最小値の長さ は許容される最大値の長さ以下でなければなりません。
制約検証: 要素に許容される最小値の長さ があり、そのdirty value flag が true で、値が 最後にユーザーの編集によって変更された場合(スクリプトによる変更ではなく)、その要素の長さが 要素の許容される最小値の長さ 未満である場合、要素は短すぎる状態になります。
この例では、4つのテキストコントロールがあります。1つ目は必須で、5文字以上である必要があります。残りの3つは任意ですが、ユーザーが入力を行った場合、少なくとも10文字以上入力する必要があります。
< form action = "/events/menu.cgi" method = "post" >
< p >< label > イベント名: < input required minlength = 5 maxlength = 50 name = event ></ label ></ p >
< p >< label > 朝食の希望があればお書きください:
< textarea name = "breakfast" minlength = "10" ></ textarea ></ label ></ p >
< p >< label > 昼食の希望があればお書きください:
< textarea name = "lunch" minlength = "10" ></ textarea ></ label ></ p >
< p >< label > 夕食の希望があればお書きください:
< textarea name = "dinner" minlength = "10" ></ textarea ></ label ></ p >
< p >< input type = submit value = "リクエストを送信" ></ p >
</ form >
disabled
属性すべての現在のエンジンでサポートされています。
すべての現在のエンジンでサポートされています。
すべての現在のエンジンでサポートされています。
すべての現在のエンジンでサポートされています。
すべての現在のエンジンでサポートされています。
disabled
コンテンツ属性はブール属性です。
disabled
属性は、option要素と
disabled
属性は、optgroup要素に対して別々に定義されています。
フォームコントロールが無効になるのは、次のいずれかの場合です:
要素がbutton、
input、
select、
textarea、
またはフォーム関連カスタム要素
であり、かつdisabled
属性がこの要素に指定されている場合(その値に関係なく)。
要素がfieldset要素の子孫であり、
そのdisabled属性が指定されていて、
かつそのfieldset要素の最初の
legend要素の子孫ではない場合。
無効になっているフォームコントロールは、disabledである場合、 タスクのキューにある ユーザー操作タスクソース からのclick イベントが要素に送信されるのを防止する必要があります。
制約検証: 要素がdisabledである場合、 それは制約検証から除外されます。
すべての現在のエンジンでサポートされています。
すべての現在のエンジンでサポートされています。
disabled
IDL 属性は、反映する必要があります。disabled
コンテンツ属性を。
Element/form#Attributes_for_form_submission
すべての現在のエンジンでサポートされています。
フォーム送信用の属性は、form要素および送信ボタン (例: input 要素のtype属性がSubmit Button 状態であるもの) に指定できます。
フォーム送信用の属性は、form要素に指定できる属性は、action、enctype、method、novalidate、およびtargetです。
対応するフォーム送信用の属性は、送信ボタンに指定できる属性は、formaction、formenctype、formmethod、formnovalidate、およびformtargetです。省略された場合、form要素の対応する属性に設定されている値がデフォルトとして使用されます。
すべての現在のエンジンでサポートされています。
action および
formaction
コンテンツ属性が指定されている場合、その値は 有効な非空の URL
である必要があります。
要素のactionは、その要素が 送信ボタン であり、その属性がある場合、その要素のformaction属性の値、またはその
フォームオーナー のaction属性の値がそれであり、ない場合は空の文字列です。
すべての現在のエンジンでサポートされています。
method
および
formmethod
コンテンツ属性は、列挙された属性であり、次のキーワードと状態を持っています:
| キーワード | 状態 | 簡単な説明 |
|---|---|---|
get
| GET | フォーム
が HTTP GET メソッドを使用することを示します。
|
post
| POST | フォーム
が HTTP POST メソッドを使用することを示します。
|
dialog
| Dialog | フォーム
が、フォームが存在する ダイアログ
ボックスを閉じることを目的としていることを示します。
フォームがダイアログにある場合は閉じ、それ以外の場合は送信しません。
|
method
属性の 欠落値のデフォルト および
無効な値のデフォルト
は、GET 状態です。
formmethod
属性には 欠落値のデフォルト
がなく、その 無効な値のデフォルト は GET 状態です。
要素の method は、これらの状態のいずれかです。要素が 送信ボタン であり、formmethod
属性がある場合、その要素の method
はその属性の状態であり、そうでなければ、
フォームの所有者 の method
属性の状態です。
ここでは、method
属性を使用してデフォルト値 "get"
を明示的に指定し、検索クエリが URL に送信されるようにします:
< form method = "get" action = "/search.cgi" >
< p >< label > Search terms: < input type = search name = q ></ label ></ p >
< p >< input type = submit ></ p >
</ form >
一方、ここでは method
属性を使用して "post"
の値を指定し、ユーザーのメッセージが HTTP リクエストの本文で送信されるようにします:
< form method = "post" action = "/post-message.cgi" >
< p >< label > Message: < input type = text name = m ></ label ></ p >
< p >< input type = submit value = "Submit message" ></ p >
</ form >
この例では、フォーム が
ダイアログ
と一緒に使用されています。
method
属性の "dialog"
キーワードを使用して、フォームが送信されるとダイアログが自動的に閉じるようにしています。
< dialog id = "ship" >
< form method = dialog >
< p > A ship has arrived in the harbour.</ p >
< button type = submit value = "board" > Board the ship</ button >
< button type = submit value = "call" > Call to the captain</ button >
</ form >
</ dialog >
< script >
var ship = document. getElementById( 'ship' );
ship. showModal();
ship. onclose = function ( event) {
if ( ship. returnValue == 'board' ) {
// ...
} else {
// ...
}
};
</ script >
すべての現在のエンジンでサポートされています。
enctype
および
formenctype
コンテンツ属性は、列挙された属性であり、次のキーワードと状態を持っています:
application/x-www-form-urlencoded" キーワードと
対応する状態。
multipart/form-data" キーワードと対応する
状態。
text/plain" キーワードと対応する状態。
属性の 欠落値のデフォルト および
無効な値のデフォルト
は、application/x-www-form-urlencoded
状態です。
formenctype
属性には 欠落値のデフォルト
がなく、その 無効な値のデフォルト は application/x-www-form-urlencoded
状態です。
要素の enctype は、これらの3つの状態のいずれかです。
要素が 送信ボタン であり、formenctype
属性がある場合、その要素の enctype
はその属性の状態であり、そうでなければ、
フォームの所有者 の enctype
属性の状態です。
すべての現在のエンジンでサポートされています。
target
および
formtarget
コンテンツ属性は、指定されている場合、有効なナビゲーブルターゲット名またはキーワード である必要があります。
すべての現在のエンジンでサポートされています。
novalidate
および formnovalidate コンテンツ属性は、ブール属性 です。存在する場合、
それらはフォームが送信時に検証されないことを示します。
要素の 検証しない状態 は、要素が 送信ボタン であり、要素の formnovalidate
属性が存在する場合、または要素の
フォーム所有者 の novalidate
属性が存在する場合に真となり、その他の場合は偽になります。
この属性は、検証制約があるフォームに「保存」ボタンを含めるのに便利であり、 ユーザーがフォームに完全に入力していない場合でも、進捗状況を保存できるようにします。次の例は、2つの必須フィールドを持つシンプルなフォームを示しています。フォームを送信するためのボタンが1つあり、これは両方のフィールドに入力される必要があります。フォームを保存するためのボタンが1つあり、ユーザーが後で記入するためにフォームを保存できるようにします。そして、フォーム全体をキャンセルするためのボタンが1つあります。
< form action = "editor.cgi" method = "post" >
< p >< label > Name: < input required name = fn ></ label ></ p >
< p >< label > Essay: < textarea required name = essay ></ textarea ></ label ></ p >
< p >< input type = submit name = submit value = "Submit essay" ></ p >
< p >< input type = submit formnovalidate name = save value = "Save essay" ></ p >
< p >< input type = submit formnovalidate name = cancel value = "Cancel" ></ p >
</ form >
すべての現在のエンジンでサポートされています。
すべての現在のエンジンでサポートされています。
すべての現在のエンジンでサポートされています。
すべての現在のエンジンでサポートされています。
すべての現在のエンジンでサポートされています。
action
IDL
属性は、同じ名前のコンテンツ属性を反映しなければならず、ただし、
取得時に、コンテンツ属性が欠落しているか、その値が空文字列の場合、要素の
ノードドキュメントのURL
が返されなければならない。
target
IDL 属性は、同じ名前のコンテンツ属性を反映しなければならない。
methodおよびenctypeID
属性は、それぞれの同じ名前のコンテンツ属性を反映しなければならない。既知の値のみに制限される。
encodingID
属性は、反映されなければならない。enctypeコンテンツ属性は既知の値のみに制限される。
noValidateID
属性は、反映されなければならない
novalidateコンテンツ属性。
formAction
IDL 属性は、反映しなければならない。formaction
コンテンツ属性は、取得時に、コンテンツ属性が欠落しているか、その値が空文字列の場合、要素の
ノードドキュメントのURL
が返されなければならない。
formEnctypeIDL 属性は、反映しなければならない
formenctypeコンテンツ属性は、既知の値のみに制限される。
formMethodIDL 属性は、反映しなければならない。
formmethod
コンテンツ属性は、既知の値のみに制限される。
formNoValidateIDL 属性は、反映
しなければならない。formnovalidateコンテンツ属性。
formTargetID
属性は、反映しなければならない。formtargetコンテンツ属性。
autocomplete
属性すべての現行エンジンでサポートされています。
ユーザーエージェントには、ユーザーがフォームに入力するのを支援する機能がある場合があります。たとえば、以前のユーザー入力に基づいてユーザーの住所を事前入力する機能です。autocomplete 属性を使用して、ユーザーエージェントにこの機能の提供方法、または提供するかどうかを示唆できます。
この属性の使用には2つの方法があります。オートフィル期待マント を身に着けている場合、autocomplete
属性は、ユーザーから期待される入力内容を説明します。オートフィルアンカーマント を身に着けている場合、autocomplete
属性は、与えられた値の意味を説明します。
属性が input
要素であり、その type
属性が 状態にある場合、autocomplete
属性は オートフィルアンカーマント
を身に着けます。他のすべての場合では、オートフィル期待マント
を身に着けます。
オートフィル期待マント
を身に着けている場合、指定されている場合は、autocomplete
属性には、次のいずれかのASCII大文字小文字を区別しない単一のトークンを含む順序付きの 空白で区切られたトークンのセット
が値として指定されている必要があります。
オートフィルアンカーマント
を身に着けている場合、指定されている場合は、autocomplete
属性には、次の順序で並べられた 空白で区切られたトークンのセット
が値として指定されている必要があります。そのトークンは オートフィル詳細トークン
でなければなりません。
(つまり、"on"
と "off"
キーワードは許可されていません)。
オートフィル詳細トークン は以下の順序で示されます:
オプションとして、先頭の8文字が "section-" と
ASCII 大文字と小文字を区別しない
文字列と一致するトークンを指定することができます。これは、フィールドが指定されたグループに属していることを意味します。
例えば、フォームに2つの配送先住所がある場合、それらは次のようにマークアップされる可能性があります:
< fieldset >
< legend > Ship the blue gift to...</ legend >
< p > < label > Address: < textarea name = ba autocomplete = "section-blue shipping street-address" ></ textarea > </ label >
< p > < label > City: < input name = bc autocomplete = "section-blue shipping address-level2" > </ label >
< p > < label > Postal Code: < input name = bp autocomplete = "section-blue shipping postal-code" > </ label >
</ fieldset >
< fieldset >
< legend > Ship the red gift to...</ legend >
< p > < label > Address: < textarea name = ra autocomplete = "section-red shipping street-address" ></ textarea > </ label >
< p > < label > City: < input name = rc autocomplete = "section-red shipping address-level2" > </ label >
< p > < label > Postal Code: < input name = rp autocomplete = "section-red shipping postal-code" > </ label >
</ fieldset >
オプションとして、次の文字列のいずれかに一致するトークンを指定することができます:
shipping",
フィールドが配送先住所や連絡先情報の一部であることを意味します
billing",
フィールドが請求先住所や連絡先情報の一部であることを意味します
次の2つのオプションのいずれか:
ASCII 大文字と小文字を区別しない一致する次のいずれかの オートフィルフィールド名で、コントロールに適さないものを除くトークン:
name"
honorific-prefix"
given-name"
additional-name"
family-name"
honorific-suffix"
nickname"
username"
new-password"
current-password"
one-time-code"
organization-title"
organization"
street-address"
address-line1"
address-line2"
address-line3"
address-level4"
address-level3"
address-level2"
address-level1"
country"
country-name"
postal-code"
cc-name"
cc-given-name"
cc-additional-name"
cc-family-name"
cc-number"
cc-exp"
cc-exp-month"
cc-exp-year"
cc-csc"
cc-type"
transaction-currency"
transaction-amount"
language"
bday"
bday-day"
bday-month"
bday-year"
sex"
url"
photo"
(これらの値の説明については、以下の表を参照してください。)
以下の順序で:
オプションとして、次の文字列のいずれかに一致するトークンを指定することができます:
home", フィールドが住居での連絡先を示していることを意味します
work", フィールドが職場での連絡先を示していることを意味します
mobile",
フィールドが場所を問わず連絡先を示していることを意味します
fax",
フィールドがファックスの連絡先を示していることを意味します
pager",
フィールドがポケットベルやビーパーの連絡先を示していることを意味します
ASCII 大文字と小文字を区別しない一致する次のいずれかの オートフィルフィールド名で、コントロールに適さないものを除くトークン:
tel"
tel-country-code"
tel-national"
tel-area-code"
tel-local"
tel-local-prefix"
tel-local-suffix"
tel-extension"
email"
impp"
(これらの値の説明については、以下の表を参照してください。)
オプションとして、次の文字列 "webauthn" に
ASCII 大文字と小文字を区別しない一致するトークンを指定することができます。
これは、ユーザーエージェントがフォームコントロールと対話する際に
公開鍵認証情報を
条件付き
仲介で表示することを意味します。webauthn
は input
および textarea
要素にのみ有効です。
前述のように、この属性とそのキーワードの意味は、その属性が身に着けているマントルに依存します。
"off"
キーワードは、コントロールの入力データが特に機密性の高いものである(例えば核兵器の起動コード)か、再利用されることがない(例えば銀行のログインに使用されるワンタイムキー)値であるか、またはドキュメントが独自の自動入力メカニズムを提供しており、ユーザーエージェントが自動入力値を提供することを望まないことを示します。
"on"
キーワードは、ユーザーエージェントがユーザーに自動入力値を提供することを許可するが、ユーザーが入力することが期待されるデータの種類についての追加情報は提供しないことを示します。ユーザーエージェントは、どの自動入力値を提案するかを決定するためにヒューリスティックを使用する必要があります。
上記の自動入力フィールドは、ユーザーエージェントがユーザーに自動入力値を提供することを許可し、期待される値の種類を指定します。それぞれのキーワードの意味は、以下の表に記載されています。
autocomplete属性が省略された場合、要素のフォームオーナーのautocomplete属性の状態に対応するデフォルト値が使用されます("on"
または "off")。フォームオーナーがない場合、"on"の値が使用されます。
上記の自動入力フィールドは、指定された種類の値がこの要素に提供される値であることを示します。それぞれのキーワードの意味は、以下の表に記載されています。
この例では、ページがトランザクションの通貨と金額を明示的に指定しています。フォームはクレジットカードやその他の請求詳細を要求しています。ユーザーエージェントはこの情報を使用して、十分な残高があり、関連する通貨をサポートするクレジットカードを提案することができます。
< form method = post action = "step2.cgi" >
< input type = hidden autocomplete = transaction-currency value = "CHF" >
< input type = hidden autocomplete = transaction-amount value = "15.00" >
< p >< label > クレジットカード番号: < input type = text inputmode = numeric autocomplete = cc-number ></ label >
< p >< label > 有効期限: < input type = month autocomplete = cc-exp ></ label >
< p >< input type = submit value = "Continue..." >
</ form >
自動入力フィールドのキーワードは、以下の表に示されているように相互に関連しています。この表の各行にリストされているフィールド名は、「意味」という列に記載されている内容に対応しています。例えば、クレジットカードの有効期限は、月と年の両方を表す1つのフィールド「cc-exp」で表現することも、月「cc-exp-month」と年「cc-exp-year」の2つのフィールドで表現することもできます。このような場合、より広範なフィールド名が複数の行にわたっており、その中で狭いフィールドが定義されています。
一般的に、作成者は狭いフィールドよりも広いフィールドを使用することを推奨します。狭いフィールドは西洋のバイアスを露呈しがちです。例えば、いくつかの西洋文化では、名前と姓がその順で配置されるのが一般的ですが、多くの文化では姓が先で名前が後になりますし、他の多くの文化では単一の名前のみを持ちます。そのため、単一のフィールドを使用する方が柔軟です。
一部のフィールドは、特定のフォームコントロールにのみ適しています。ある自動入力フィールド名がコントロールに対して不適切であるのは、そのコントロールが表の最初の行の5列目でその自動入力フィールドにリストされているグループに属していない場合です。どのコントロールがどのグループに属するかは、表の下に記載されています。
| フィールド名 | 意味 | 標準形式 | 標準形式の例 | コントロールグループ | |||
|---|---|---|---|---|---|---|---|
"name" |
フルネーム | 自由形式のテキスト、改行なし | Sir Timothy John Berners-Lee, OM, KBE, FRS, FREng, FRSA | テキスト | |||
"honorific-prefix" |
敬称またはタイトル(例:"Mr.", "Ms.", "Dr.", "Mlle") | 自由形式のテキスト、改行なし | Sir | テキスト | |||
"given-name" |
名前(いくつかの西洋文化ではファーストネームとしても知られている) | 自由形式のテキスト、改行なし | Timothy | テキスト | |||
"additional-name" |
追加の名前(いくつかの西洋文化ではミドルネーム、ファーストネーム以外の他の名前としても知られている) | 自由形式のテキスト、改行なし | John | テキスト | |||
"family-name"
|
姓(いくつかの西洋文化ではラストネームまたは姓としても知られている) | 自由形式のテキスト、改行なし | Berners-Lee | テキスト | |||
"honorific-suffix" |
敬称の後置(例:"Jr.", "B.Sc.", "MBASW", "II") | 自由形式のテキスト、改行なし | OM, KBE, FRS, FREng, FRSA | テキスト | |||
"nickname" |
ニックネーム、スクリーンネーム、ハンドル:フルネームの代わりに使用されることが多い短い名前 | 自由形式のテキスト、改行なし | Tim | テキスト | |||
"organization-title" |
職位(例:"Software Engineer", "Senior Vice President", "Deputy Managing Director") | 自由形式のテキスト、改行なし | 教授 | テキスト | |||
"username" |
ユーザー名 | 自由形式のテキスト、改行なし | timbl | ユーザー名 | |||
"new-password"
|
新しいパスワード(例:アカウント作成時またはパスワード変更時) | 自由形式のテキスト、改行なし | GUMFXbadyrS3 | パスワード | |||
"current-password" |
ユーザー名フィールドで識別されるアカウントの現在のパスワード(例:ログイン時)
|
自由形式のテキスト、改行なし | qwerty | パスワード | |||
"one-time-code"
|
ユーザーの身元を確認するためのワンタイムコード | 自由形式のテキスト、改行なし | 123456 | パスワード | |||
"organization"
| このフィールドに関連する他のフィールドに含まれる人物、住所、または連絡先情報に対応する会社名 | 自由形式のテキスト、改行なし | World Wide Web Consortium | Text | |||
"street-address"
| 住所(複数行、改行保持) | 自由形式のテキスト | 32 Vassar Street MIT Room 32-G524 | Multiline | |||
"address-line1"
| 住所(各フィールドに1行) | 自由形式のテキスト、改行なし | 32 Vassar Street | Text | |||
"address-line2"
| 自由形式のテキスト、改行なし | MIT Room 32-G524 | Text | ||||
"address-line3"
| 自由形式のテキスト、改行なし | Text | |||||
"address-level4"
| 最も細かい行政区分、4つの行政区分を持つ住所で | 自由形式のテキスト、改行なし | Text | ||||
"address-level3"
| 3番目の行政区分、3つ以上の行政区分を持つ住所で | 自由形式のテキスト、改行なし | Text | ||||
"address-level2"
| 2番目の行政区分、2つ以上の行政区分を持つ住所で;2つの行政区分を持つ国では、通常該当する住所が含まれる市町村や他の地域 | 自由形式のテキスト、改行なし | Cambridge | Text | |||
"address-level1"
| 住所の最も広範な行政区分、つまり、該当する住所が含まれる州; スイスの場合はカントン; イギリスでは、郵便区 | 自由形式のテキスト、改行なし | MA | Text | |||
"country"
| 国コード | 有効なISO 3166-1-alpha-2 country code [ISO3166] | US | Text | |||
"country-name"
| 国名 | 自由形式のテキスト、改行なし; countryから派生した場合もある
| US | Text | |||
"postal-code"
| 郵便番号、ZIPコード、CEDEXコード(CEDEXの場合、address-level2フィールドに"CEDEX"と関連するarrondissementを追加する)
| 自由形式のテキスト、改行なし | 02139 | Text | |||
"cc-name"
| 支払手段に記載されているフルネーム | 自由形式のテキスト、改行なし | Tim Berners-Lee | Text | |||
"cc-given-name"
| 支払手段に記載されている名前(いくつかの西洋文化ではファーストネームとしても知られている) | 自由形式のテキスト、改行なし | Tim | Text | |||
"cc-additional-name"
| 支払手段に記載されている追加の名前(いくつかの西洋文化ではミドルネーム、ファーストネーム以外の他の名前としても知られている) | 自由形式のテキスト、改行なし | Text | ||||
"cc-family-name"
| 支払手段に記載されている姓(いくつかの西洋文化ではラストネームまたは姓としても知られている) | 自由形式のテキスト、改行なし | Berners-Lee | Text | |||
"cc-number"
| 支払手段を識別するコード(例:クレジットカード番号) | ASCII数字 | 4114360123456785 | Text | |||
"cc-exp"
| 支払手段の有効期限 | 有効な月の文字列 | 2014-12 | Month | |||
"cc-exp-month"
| 支払手段の有効期限の月の部分 | 有効な整数 1..12の範囲 | 12 | Numeric | |||
"cc-exp-year"
| 支払手段の有効期限の年の部分 | 有効な整数 | 2014 | Numeric | |||
"cc-csc"
| 支払手段のセキュリティコード(カードセキュリティコード(CSC)、カード認証コード(CVC)、カード検証値(CVV)、署名パネルコード(SPC)、クレジットカードID(CCID)などとしても知られる) | ASCII数字 | 419 | Text | |||
"cc-type"
| 支払手段の種類 | 自由形式のテキスト、改行なし | Visa | Text | |||
"transaction-currency"
| ユーザーが希望する取引に使用する通貨 | ISO 4217通貨コード [ISO4217] | GBP | Text | |||
"transaction-amount"
| ユーザーが取引に希望する金額(例:入札や販売価格を入力する際) | 有効な浮動小数点数 | 401.00 | Numeric | |||
"language"
| 希望する言語 | 有効なBCP 47言語タグ [BCP47] | en | Text | |||
"bday"
| 誕生日 | 有効な日付文字列 | 1955-06-08 | Date | |||
"bday-day"
| 誕生日の曜日部分 | 有効な整数 1..31の範囲 | 8 | Numeric | |||
"bday-month"
| 誕生日の月の部分 | 有効な整数 1..12の範囲 | 6 | Numeric | |||
"bday-year"
| 誕生日の年の部分 | 有効な整数 0以上 | 1955 | Numeric | |||
"sex"
| 性別(例:女性、Fa'afafine) | 自由形式のテキスト、改行なし | Male | Text | |||
"url"
| このフィールドに関連する会社、人物、住所、または連絡先情報に対応するホームページや他のウェブページ | 有効なURL文字列 | https://www.w3.org/People/Berners-Lee/ | URL | |||
"photo"
| このフィールドに関連する会社、人物、住所、または連絡先情報に対応する写真、アイコン、その他の画像 | 有効なURL文字列 | https://www.w3.org/Press/Stock/Berners-Lee/2001-europaeum-eighth.jpg | URL | |||
"tel"
| 国番号を含む完全な電話番号 | ASCII数字とU+0020スペース文字、U+002Bプラス記号で始まる | +1 617 253 5702 | Tel | |||
"tel-country-code"
| 電話番号の国番号部分 | ASCII数字、U+002Bプラス記号で始まる | +1 | Text | |||
"tel-national"
| 国内プレフィックスが適用される場合、国番号部分なしの電話番号 | ASCII数字とU+0020スペース文字 | 617 253 5702 | Text | |||
"tel-area-code"
| 電話番号の市外局番部分、国内プレフィックスが適用される場合 | ASCII数字 | 617 | Text | |||
"tel-local"
| 電話番号の市外局番なしの部分 | ASCII数字 | 2535702 | Text | |||
"tel-local-prefix"
| 電話番号の市外局番の次にくる部分が2つに分かれている場合の前半部分 | ASCII数字 | 253 | Text | |||
"tel-local-suffix"
| 電話番号の市外局番の次にくる部分が2つに分かれている場合の後半部分 | ASCII数字 | 5702 | Text | |||
"tel-extension"
| 電話番号の内線番号 | ASCII数字 | 1000 | Text | |||
"email"
| メールアドレス | 有効なメールアドレス | timbl@w3.org | Username | |||
"impp"
| インスタントメッセージングプロトコルのエンドポイントを表すURL(例:"aim:goim?screenname=example"や"xmpp:fred@example.net")
| 有効なURL文字列 | irc://example.org/timbl,isuser | URL | |||
グループは次のようにコントロールに対応しています:
input要素で、type属性がHidden状態のもの
input要素で、type属性がText状態のもの
input要素で、type属性がSearch状態のもの
textarea要素
select要素
input要素で、type属性がHidden状態のもの
textarea要素
select要素
input要素で、type属性がHidden状態のもの
input要素で、type属性がText状態のもの
input要素で、type属性がSearch状態のもの
input要素で、type属性がPassword状態のもの
textarea要素
select要素
input要素で、type属性がHidden状態のもの
input要素で、type属性がText状態のもの
input要素で、type属性がSearch状態のもの
input要素で、type属性がURL状態のもの
textarea要素
select要素
input要素で、type属性がHidden状態のもの
input要素で、type属性がText状態のもの
input要素で、type属性がSearch状態のもの
input要素で、type属性がEmail状態のもの
textarea要素
select要素
input要素で、type属性がHidden状態のもの
input要素で、type属性がText状態のもの
input要素で、type属性がSearch状態のもの
input要素で、type属性がTelephone状態のもの
textarea要素
select要素
input要素で、type属性がHidden状態のもの
input要素で、type属性がText状態のもの
input要素で、type属性がSearch状態のもの
input要素で、type属性がNumber状態のもの
textarea要素
select要素
input要素で、type属性がHidden状態のもの
input要素で、type属性がText状態のもの
input要素で、type属性がSearch状態のもの
input要素で、type属性がMonth状態のもの
textarea要素
select要素
input要素で、type属性がHidden状態のもの
input要素で、type属性がText状態のもの
input要素で、type属性がSearch状態のもの
input要素で、type属性がDate状態のもの
textarea要素
select要素
アドレスレベル: "address-level1"
– "address-level4"フィールドは、住所の地域を記述するために使用されます。さまざまな地域で使用されるレベルの数は異なります。たとえば、米国では2つのレベル(州と町)が使用され、英国では住所に応じて1つまたは2つ(郵便町、および一部のケースでは地域)が使用され、中国では3つ(省、市、区)が使用されます。"address-level1"フィールドは、最も広範な行政区分を表します。さまざまな地域では、フィールドの順序が異なります。たとえば、米国では町(レベル2)が州(レベル1)の前にありますが、日本では都道府県(レベル1)が市(レベル2)の前にあり、その後に区(レベル3)が続きます。著者は、国の慣習に合わせてフォームを提供することを推奨します(ユーザーが国を変更する際にフィールドを非表示、表示、および再配置するなど)。
各input要素で、autocomplete属性が適用されるもの、および各select要素、およびtextarea要素は、自動入力ヒントセット、自動入力スコープ、自動入力フィールド名、非自動入力認証タイプ、およびIDLに公開された自動入力値を持ちます。
自動入力フィールド名は、そのフィールドで期待される特定のデータの種類を指定します。例としては、"street-address"や"cc-exp"などがあります。
自動入力ヒントセットは、ユーザーエージェントが参照すべき住所または連絡先情報の種類を識別します。例としては、"shippingfax"や"billing"などがあります。
非自動入力認証タイプは、ユーザーがフィールドと対話する際に、他の自動入力フィールド値と共にユーザーエージェントによって提供される可能性がある認証情報の種類を識別します。この値が"webauthn"であり、nullではない場合、そのタイプの認証情報を選択すると、条件付きメディエーションのnavigator.credentials.get()リクエストが解決され、自動入力が行われません。
例えば、サインインページがユーザーエージェントに保存されたパスワードを自動入力するか、公開鍵認証情報を表示して、navigator.credentials.get()リクエストを解決するよう指示することができます。ユーザーはどちらかを選択してサインインできます。
< input name = password type = password autocomplete = "current-password webauthn" >
自動入力スコープは、同じ対象に関する情報を持つフィールドのグループを識別し、自動入力ヒントセットに、必要に応じて"section-*"プレフィックスを付けたものから構成されます。例としては、"billing"、"section-parent shipping"、"section-child shipping home"などがあります。
これらの値は、次のアルゴリズムを実行した結果として定義されます:
要素にautocomplete属性がない場合は、defaultとラベル付けされたステップに移動します。
tokensを、属性の値をASCIIホワイトスペースで分割した結果とします。
tokensが空の場合、defaultとラベル付けされたステップに移動します。
indexをtokens内の最後のトークンのインデックスとします。
fieldをtokensのindex番目のトークンとします。
fieldを与えられたときにフィールドのカテゴリを決定する結果として、categoryとmaximum tokensのペアを設定します。
categoryがnullである場合、defaultとラベル付けされたステップに移動します。
tokensのトークン数がmaximum tokensを超える場合、defaultとラベル付けされたステップに移動します。
categoryがOffまたはAutomaticであり、要素のautocomplete属性が自動入力アンカーマントルを身に着けている場合、defaultとラベル付けされたステップに移動します。
categoryがOffである場合、要素の自動入力フィールド名を文字列"off"に設定し、その自動入力ヒントセットを空に設定し、そのIDLに公開された自動入力値を文字列"off"に設定します。その後、戻ります。
categoryがAutomaticである場合、要素の自動入力フィールド名を文字列"on"に設定し、その自動入力ヒントセットを空に設定し、そのIDLに公開された自動入力値を文字列"on"に設定します。その後、戻ります。
scope tokensを空のリストに設定します。
hint tokensを空のセットに設定します。
credential typeをnullに設定します。
IDL valueをfieldと同じ値に設定します。
categoryがCredentialであり、tokensのindex番目のトークンがwebauthnとASCII大文字小文字を区別しない形で一致する場合は、次のサブステップを実行します。
credential typeを"webauthn"に設定します。
トークンが最初のエントリである場合、doneとラベル付けされたステップに移動します。
indexを1減らします。
categoryとmaximum tokensのペアをindex番目のトークンに対してフィールドのカテゴリを決定する結果に設定します。
categoryがNormalまたはContactでない場合、defaultとラベル付けされたステップに移動します。
トークンの残りの数がmaximum tokensより多い場合、defaultとラベル付けされたステップに移動します。
IDL valueをindex番目のトークン、U+0020スペース文字、および以前のIDL valueの値の連結に設定します。
トークンが最初のエントリである場合、doneとラベル付けされたステップに移動します。
indexを1減らします。
categoryがContactであり、index番目のトークンが次の文字列の1つとASCII大文字小文字を区別しない形で一致する場合、次のサブステップを実行します。
サブステップは次のとおりです。
contactを上記のリストから一致する文字列に設定します。
contactをscope tokensの先頭に挿入します。
contactをhint tokensに追加します。
IDL valueをcontact、U+0020スペース文字、および以前のIDL valueの値の連結に設定します。
トークンが最初のエントリである場合、doneとラベル付けされたステップに移動します。
indexを1減らします。
トークンが次の文字列のいずれかとASCII大文字小文字を区別しない形で一致する場合、次のサブステップを実行します。
サブステップは次のとおりです。
modeを上記のリストから一致する文字列に設定します。
modeをscope tokensの先頭に挿入します。
modeをhint tokensに追加します。
IDL valueをmode、U+0020スペース文字、および以前のIDL valueの値の連結に設定します。
トークンが最初のエントリである場合、doneとラベル付けされたステップに移動します。
indexを1減らします。
トークンが最初のエントリでない場合、defaultとラベル付けされたステップに移動します。
index番目のトークンの最初の8文字が、文字列"section-"とASCII大文字小文字を区別しない形で一致しない場合、defaultとラベル付けされたステップに移動します。
sectionをindex番目のトークンに設定し、ASCII小文字に変換します。
sectionをscope tokensの先頭に挿入します。
IDL valueをsection、U+0020スペース文字、および以前のIDL valueの値の連結に設定します。
完了: 要素の自動入力ヒントセットをhint tokensに設定します。
要素の非自動入力認証タイプをcredential typeに設定します。
要素の自動入力スコープをscope tokensに設定します。
要素の自動入力フィールド名をfieldに設定します。
要素のIDLに公開された自動入力値をIDL valueに設定します。
戻ります。
デフォルト: 要素のIDLに公開された自動入力値を空文字列に設定し、その自動入力ヒントセットおよび自動入力スコープを空に設定します。
要素のautocomplete属性が自動入力アンカーマントルを身に着けている場合、要素の自動入力フィールド名を空文字列に設定し、戻ります。
formを、要素のフォーム所有者とし、存在しない場合はnullとします。
formがnullでなく、そのautocomplete属性がオフ状態である場合、要素の自動入力フィールド名を"off"に設定します。
それ以外の場合、要素の自動入力フィールド名を"on"に設定します。
次のようにしてフィールドのカテゴリを決定します、与えられたfieldに基づいて:
fieldが次の表の最初の列に記載されているトークンのいずれかとASCII大文字と小文字を区別しない一致を持たない場合、(null, null)のペアを返します。
それ以外の場合、maximum tokensおよびcategoryは、それぞれその行の第2列および第3列の値とします。
ペア(category, maximum tokens)を返します。
オートフィルの目的において、コントロールのデータはコントロールの種類に依存します:
input要素で、type属性がEmail状態にあり、multiple属性が指定されている場合
input要素
textarea要素
select要素で、multiple属性が指定されている場合
option要素のオプションリストで、選択状態がtrueに設定されているもの。
select要素
option要素のオプションリストで、選択状態がtrueに設定されているもの。
オートフィルの処理方法は、オートフィルヒントセット、オートフィルスコープ、およびオートフィルフィールド名の内容が、autocomplete属性がどのマントルを着ているかに依存します。
要素のオートフィルフィールド名が"off"である場合、ユーザーエージェントはコントロールのデータを記憶せず、過去の値をユーザーに提示することもありません。
さらに、要素のオートフィルフィールド名が"off"である場合、値はリセットされますがドキュメントを再アクティブ化するときに。
銀行は頻繁にユーザーエージェントがログイン情報を事前入力しないことを望んでいます:
< p >< label > Account: < input type = "text" name = "ac" autocomplete = "off" ></ label ></ p >
< p >< label > PIN: < input type = "password" name = "pin" autocomplete = "off" ></ label ></ p >
要素のオートフィルフィールド名が"off"でない場合、ユーザーエージェントはコントロールのデータを保存し、以前に保存された値をユーザーに提示することができます。
例えば、ユーザーが次のようなコントロールがあるページにアクセスしたとします:
< select name = "country" >
< option > Afghanistan
< option > Albania
< option > Algeria
< option > Andorra
< option > Angola
< option > Antigua and Barbuda
< option > Argentina
< option > Armenia
<!-- ... -->
< option > Yemen
< option > Zambia
< option > Zimbabwe
</ select >
このコントロールは次のようにレンダリングされるかもしれません:

このページを初めて訪問したとき、ユーザーが「Zambia」を選択したと仮定します。2回目の訪問では、ユーザーエージェントは「Zambia」のエントリをリストの最上部に複製し、インターフェースは次のようになります:
要素のオートフィルフィールド名が"on"の場合、ユーザーエージェントはヒューリスティクスを使用して、要素のname値、要素が所属するフォームの他のフィールドなどに基づいて、ユーザーに提示する最も適切な値を決定しようとするべきです。
要素のオートフィルフィールド名がこのセクションの前述の表に記載されているオートフィルフィールドの名前の1つである場合、ユーザーエージェントはそのフィールド名の意味に一致する提案を提供するべきです。オートフィルヒントセットは複数の候補から選択するために使用されるべきです。
例えば、あるユーザーがかつて「shipping」キーワードを使用したフィールドに1つの住所を入力し、別の住所を「billing」キーワードを使用したフィールドに入力した場合、その後のフォームでは、オートフィルヒントセットに「shipping」キーワードが含まれるフォームコントロールには最初の住所だけが提案されるでしょう。ただし、住所関連のフォームコントロールでオートフィルヒントセットにどちらのキーワードも含まれない場合、両方の住所が提案されるかもしれません。
要素のオートフィルフィールド名が空文字列でない場合、ユーザーエージェントはユーザーが指定したものと同じように、コントロールのデータを指定されたオートフィルヒントセット、オートフィルスコープ、およびオートフィルフィールド名の組み合わせに基づいて処理しなければなりません。
ユーザーエージェントがフォームコントロールをオートフィルする際、同じフォームオーナーと同じオートフィルスコープを持つ要素は、同じ人、住所、支払い手段、および連絡先情報に関連するデータを使用しなければなりません。ユーザーエージェントが"country"フィールドと"country-name"フィールドを同じフォームオーナーおよびオートフィルスコープでオートフィルする際、ユーザーエージェントがcountryフィールドに値を持っている場合は、country-nameフィールドには同じ国の人間が読める名前で埋める必要があります。
ユーザーエージェントが複数のフィールドに同時に値を入力する場合、同じオートフィルフィールド名、フォームオーナー、およびオートフィルスコープを持つフィールドは、同じ値で埋められなければなりません。
例えば、ユーザーエージェントが2つの電話番号、+1 555 123 1234と+1 555 666
7777を知っていると仮定します。ユーザーエージェントが、autocomplete="shipping tel-local-prefix"であるフィールドに"123"の値を入力し、同じフォーム内の別のフィールドにautocomplete="shipping tel-local-suffix"で"7777"の値を入力するのは規定に準拠していません。上述の情報を考慮すると、有効な事前入力の値はそれぞれ"123"と"1234"、または"666"と"7777"のみです。
同様に、何らかの理由で"cc-exp"フィールドと"cc-exp-month"フィールドが含まれているフォームがあり、ユーザーエージェントがそのフォームを事前入力する場合、前者の月の要素は後者と一致しなければなりません。
この要件はオートフィルアンカーマントルにも影響します。次のマークアップスニペットを考えてみましょう:
< form >
< input type = hidden autocomplete = "nickname" value = "TreePlate" >
< input type = text autocomplete = "nickname" >
</ form >
この場合、準拠するユーザーエージェントがテキストコントロールに提案できる唯一の値は、hidden input要素によって与えられた"TreePlate"です。
"section-*"トークンはオートフィルスコープ内で不透明です。ユーザーエージェントはこれらのトークンの正確な値から意味を導き出そうとしてはなりません。
例えば、ユーザーエージェントが"section-child"にユーザーの子供の住所を提案し、"section-spouse"にユーザーの配偶者の住所を提案するのは規定に準拠していません。
オートフィル機構は、ユーザーがコントロールのデータを変更したかのようにユーザーエージェントが動作することによって実装されなければならず、要素が変更可能な時点で行われなければなりません(例:要素がドキュメントに挿入された直後、またはユーザーエージェントが解析を停止するときなど)。ユーザーエージェントは、ユーザーが入力した可能性のある値を使用してのみ、コントロールを事前入力しなければなりません。
例えば、select要素にoption要素が"Steve"、"Rebecca"、"Jay"、"Bob"という値のみを持ち、オートフィルフィールド名が"given-name"である場合、ユーザーエージェントが事前入力する唯一のアイデアが"Evan"であると仮定します。その場合、ユーザーエージェントはフィールドを事前入力することはできません。select要素に"Evan"という値を設定することは準拠していません。ユーザーが自分でそのようにすることができないからです。
ユーザーエージェントがフォームコントロールを事前入力する際、ドキュメントツリー内にあるフォームコントロールと接続されているフォームコントロールを差別してはなりません。つまり、要素のルートがシャドウルートであるか、Documentであるかに基づいて、オートフィルを行うかどうかを決定するのは準拠していません。
ユーザーエージェントがフォームコントロールの値を自動入力する際、そのコントロールがタイプミスマッチの状態、長すぎる状態、短すぎる状態、アンダーフロー状態、オーバーフロー状態、またはステップミスマッチ状態に陥らせてはなりません。ユーザーエージェントがフォームコントロールの値を自動入力する際、そのコントロールがパターンミスマッチ状態に陥らせてもいけません。コントロールの制約に基づいて可能な場合、ユーザーエージェントは前述の表で規定された正規の形式を使用する必要があります。正規の形式を使用できない場合、ユーザーエージェントは値を使用できるように変換するためのヒューリスティックを試みるべきです。
たとえば、ユーザーエージェントがユーザーのミドルネームが「Ines」であることを知っており、次のようなフォームコントロールに事前入力しようとする場合:
< input name = middle-initial maxlength = 1 autocomplete = "additional-name" >
...ユーザーエージェントは「Ines」を「I」に変換し、そのように事前入力することができます。
さらに複雑な例として、月の値があります。ユーザーエージェントがユーザーの誕生日が2012年7月27日であることを知っている場合、次のコントロールすべてに対して、この情報に基づいてわずかに異なる値を事前入力しようとする可能性があります:
| 2012-07 |
日付は削除されます。なぜなら、Month状態では月/年の組み合わせのみが受け入れられるためです。(この例は非準拠です。なぜなら、オートフィルフィールド名
bday
は
Month状態で許可されていません。)
|
| July | ユーザーエージェントは、12個のオプションがあり、7番目を選択するか、文字列(3文字の「Jul」、改行およびスペースで区切られたもの)がユーザーエージェントがサポートする言語の1つで月の名前(July)に近い一致であることを認識するなどのメカニズムを通じて、リストされたオプションから月を選択します。 |
| 7 | ユーザーエージェントは「July」を1から12の範囲の月番号に変換します。 |
| 6 | ユーザーエージェントは「July」を0から11の範囲の月番号に変換します。 |
| ユーザーエージェントはフィールドに入力しません。なぜなら、フォームが何を期待しているのか良い推測ができないからです。 |
ユーザーエージェントは、要素のオートフィルフィールド名を上書きすることを許可する場合があります。たとえば、ページ作成者の反対にもかかわらず値を記憶し、事前入力できるようにするために、"off"を"on"に変更したり、常に"off"にして値を記憶しないようにするなどです。
より具体的には、ユーザーエージェントは、次の表の最初の列に記載されている説明に一致するフォームコントロールのオートフィルフィールド名を、オートフィルフィールド名が"on"または"off"である場合に、2番目のセルに示された値で置き換えることを考慮する場合があります。この表が使用される場合、置換はツリー順で行う必要があります。最初の行を除いてすべての行は、前の要素のオートフィルフィールド名を参照しているためです。
以下の説明で、フォームコントロールが他のフォームコントロールの前または後に配置されていることに言及する場合、それらは同じフォーム所有者を共有するリストされた要素のリストで意味します。
| フォームコントロール | 新しいオートフィルフィールド名 |
|---|---|
input
要素で、type
属性が
テキスト状態にあり、その後に
input
要素で、type
属性が
パスワード状態にあるもの
|
"username"
|
input
要素で、type
属性が
パスワード状態にあり、その前に
input
要素で、オートフィルフィールド名が"username"であるもの
|
"current-password"
|
input
要素で、type
属性が
パスワード状態にあり、その前に
input
要素で、オートフィルフィールド名が"current-password"であるもの
|
"new-password"
|
input
要素で、type
属性が
パスワード状態にあり、その前に
input
要素で、オートフィルフィールド名が"new-password"であるもの
|
"new-password"
|
取得時に、autocompleteIDL属性は要素のIDL公開オートフィル値を返し、設定時には同じ名前のコンテンツ属性を反映する必要があります。
input要素とtextarea要素は、それぞれの選択を処理するためのいくつかの属性とメソッドを定義しています。それらの共有アルゴリズムがここに定義されています。
element.select()
テキストコントロール内のすべてを選択します。
element.selectionStart [ = value ]
選択範囲の開始位置のオフセットを返します。
設定することで、選択範囲の開始位置を変更できます。
element.selectionEnd [ = value ]
選択範囲の終了位置のオフセットを返します。
設定することで、選択範囲の終了位置を変更できます。
element.selectionDirection [ = value ]
現在の選択の方向を返します。
設定することで、選択の方向を変更できます。
可能な値は「forward」、「backward」、および「none」です。
element.setSelectionRange(start, end [, direction])
HTMLInputElement/setSelectionRange
すべての現在のエンジンでサポートされています。
指定された方向で、指定された部分文字列を含むように選択範囲を変更します。方向が省略された場合、それはプラットフォームのデフォルト(noneまたはforward)にリセットされます。
element.setRangeText(replacement [, start, end [, selectionMode ] ])
すべての現在のエンジンでサポートされています。
テキストの範囲を新しいテキストで置き換えます。startとendの引数が指定されていない場合、範囲は選択範囲であると見なされます。
最後の引数は、テキストが置き換えられた後に選択がどのように設定されるかを決定します。可能な値は次のとおりです:
select"
start"
end"
preserve"
すべてのinput要素にこれらのAPIが適用され、すべてのtextarea要素には、常に選択範囲またはテキスト入力カーソル位置が存在します(レンダリングされていない要素でも)。これは、コントロールのコード単位で測定され、初期状態ではコントロールの先頭にテキスト入力カーソルが配置されます。
input要素の場合、これらのAPIは要素の値に対して操作を行う必要があります。textarea要素の場合、これらのAPIは要素のAPI値に対して操作を行う必要があります。以下のアルゴリズムでは、操作対象の値文字列を関連値と呼びます。
API値を使用することは、textarea要素に対して、U+000D(CR)文字が正規化されることを意味します。例えば、
< textarea id = "demo" ></ textarea >
< script >
demo. value = "A\r\nB" ;
demo. setRangeText( "replaced" , 0 , 2 );
assert( demo. value === "replacedB" );
</ script >
もし「A\r\nB」の生の値を操作していた場合、「A\r」という文字が置き換えられ、「replaced\nB」という結果になります。しかし、API値「A\nB」を使用したため、「A\n」の文字を置き換えて「replacedB」が得られました。
U+200D ゼロ幅結合子などの表示されない文字も、文字としてカウントされます。したがって、たとえば、選択範囲が目に見えない文字だけを含む場合や、テキスト挿入カーソルがそのような文字の片側に配置される場合があります。
これらのAPIが適用される要素の関連値が変更されるたびに、次の手順を実行します:
要素が選択範囲を持っている場合:
それ以外の場合、要素はテキスト入力カーソル位置を持っている必要があります。これが現在関連値の終了位置を超えている場合、それを関連値の終了位置に設定します。
場合によっては、関連値が変更されると、他の仕様部分がカーソル位置を変更することもあります。たとえば、値セッターを参照してください。
可能な限り、inputおよびtextarea要素でのテキスト選択を変更するためのユーザーインターフェース機能は、同じイベントが発生するようにするために、選択範囲を設定するアルゴリズムを使用して実装される必要があります。
inputおよびtextarea要素の選択には、選択方向があります。これは「forward」、「backward」、または「none」のいずれかです。選択方向の正確な意味はプラットフォームによって異なります。この方向はユーザーが選択を操作する際に設定されます。初期の選択方向は、プラットフォームがその方向をサポートしている場合は「none」、そうでない場合は「forward」でなければなりません。
選択方向を設定するには、要素の選択方向を指定された方向に更新します。ただし、方向が「none」であり、プラットフォームがその方向をサポートしていない場合は、要素の選択方向を「forward」に更新します。
Windowsでは、方向は選択範囲に対するカーソルの位置を示します。「forward」の選択は、カーソルが選択範囲の終わりにあり、「backward」の選択は、カーソルが選択範囲の先頭にあります。Windowsには「none」方向はありません。
Macでは、方向はユーザーがShiftキーを使用して選択範囲を調整する際にどの端が影響を受けるかを示します。「forward」方向は選択範囲の終わりが変更され、「backward」方向は選択範囲の先頭が変更されます。Macでは「none」がデフォルトで、まだ特定の方向が選択されていないことを示します。ユーザーは、選択範囲を初めて調整するときに使用された矢印キーに基づいて、暗黙的に方向を設定します。
すべてのエンジンでサポートされています。
select()メソッドが呼び出されたとき、以下の手順を実行する必要があります。
この要素がinput要素であり、select()がこの要素に適用されないか、対応するコントロールに選択可能なテキストがない場合、処理を終了します。
たとえば、<input type=color>がカラーウェルとしてレンダリングされ、16進カラーコードを受け付けるテキストコントロールではないユーザーエージェントでは、このメソッドが呼び出されても無視されます。
選択範囲を設定します。開始位置は0、終了位置は無限大です。
selectionStart属性のゲッターは、次の手順を実行する必要があります。
この要素がinput要素であり、
selectionStart
がこの要素に適用されない場合、nullを返します。
選択がない場合、selectionのすぐ後に続く文字の コード単位オフセットを返します。これにより、 関連する値の中で テキスト入力カーソルが位置する場所がわかります。
コード単位のオフセットを返します。これにより、 関連する値の中で selectionの開始部分が位置する場所がわかります。
selectionStart
属性のセッターは、次の手順を実行する必要があります。
この要素がinput要素であり、
selectionStart
がこの要素に適用されない場合、
"InvalidStateError"
DOMExceptionをスローします。
endを、この要素のselectionEnd
属性の値に設定します。
endが与えられた値より小さい場合、endを与えられた値に設定します。
選択範囲を設定します。この範囲は、与えられた値、end、およびこの要素のselectionDirection
属性の値を使用して設定されます。
selectionEnd属性のゲッターは、次の手順を実行する必要があります。
この要素がinput要素であり、
selectionEnd
がこの要素に適用されない場合、nullを返します。
選択がない場合、selectionのすぐ後に続く文字の コード単位オフセットを返します。これにより、 関連する値の中で テキスト入力カーソルが位置する場所がわかります。
コード単位のオフセットを返します。これにより、 関連する値の中で selectionの終了部分が位置する場所がわかります。
selectionEnd
属性のセッターは、次の手順を実行する必要があります。
この要素がinput要素であり、
selectionEnd
がこの要素に適用されない場合、
"InvalidStateError"
DOMExceptionをスローします。
選択範囲を設定します。この範囲は、この要素のselectionStart
属性の値、与えられた値、および
この要素のselectionDirection
属性の値を使用して設定されます。
selectionDirection属性のゲッターは、次の手順を実行する必要があります。
この要素がinput要素であり、
selectionDirection
がこの要素に適用されない場合、
nullを返します。
この要素の選択方向を返します。
selectionDirection
属性のセッターは、次の手順を実行する必要があります。
この要素がinput要素であり、
selectionDirection
がこの要素に適用されない場合、
"InvalidStateError"
DOMExceptionをスローします。
選択範囲を設定します。この範囲は、この要素のselectionStart
属性の値、selectionEnd
属性の値、および与えられた値を使用して設定されます。
setSelectionRange(start, end,
direction)メソッドが呼び出されたとき、次の手順を実行する必要があります。
この要素がinput要素であり、
setSelectionRange()
がこの要素に適用されない場合、
"InvalidStateError"
DOMExceptionをスローします。
選択範囲を設定します。範囲は、start、end、およびdirectionを使用して設定されます。
選択範囲を設定するために、整数またはnullのstart、整数またはnullまたは特別な値infinityのend、およびオプションで文字列のdirectionを使用して、次の手順を実行します。
startがnullの場合、startをゼロに設定します。
endがnullの場合、endをゼロに設定します。
テキストコントロールのselectionを、コード単位のシーケンスとして設定します。このシーケンスは、関連する値内のstart番目の位置(論理順序)から始まり、end番目の位置までのコード単位で構成されます。引数がテキストコントロールの長さ(特別な値infinityを含む)よりも大きい場合、テキストコントロールの末尾を指すものと見なされます。endがstartより小さいか等しい場合、選択範囲の開始位置と終了位置は、endに対応する文字の直前に設定されます。空の選択範囲の概念がないUAでは、カーソルはendに対応する文字の直前に設定されます。
directionが"backward"または"forward"のどちらかと同一でない場合、またはdirection引数が与えられていない場合、directionを"none"に設定します。
テキストコントロールの選択方向を設定します。この方向は、directionに基づき設定されます。
前の手順によってテキストコントロールのselectionが変更された場合(範囲や方向が変更された場合)、要素タスクをキューに入れる必要があります。このタスクは、ユーザーインタラクションタスクソースに基づいて、要素でイベントを発火させるものです。このイベントの名前はselectであり、bubbles属性はtrueに初期化されます。
setRangeText(replacement, start,
end, selectMode)メソッドが呼び出されたとき、次の手順を実行する必要があります。
この要素がinput要素であり、
setRangeText()
がこの要素に適用されない場合、
"InvalidStateError"
DOMExceptionをスローします。
この要素の汚れた値フラグを trueに設定します。
メソッドに引数が1つしかない場合、startおよびendの値をselectionStart
属性とselectionEnd
属性の値に設定します。
それ以外の場合、startおよびendの値を2番目および3番目の引数の値に設定します。
startがendより大きい場合、"IndexSizeError" DOMExceptionをスローします。
selection startをselectionStart
属性の現在の値に設定します。
selection endをselectionEnd
属性の現在の値に設定します。
startがendより小さい場合、要素のコード単位のシーケンスを削除します。このシーケンスは、関連する値の中のstart番目の位置から始まり、end-1番目の位置で終わります。
new lengthを最初の引数の長さに設定します。
new endをstartとnew lengthの和に設定します。
次のリストから適切なサブステップセットを実行します。
select"の場合
selection startをstartに設定します。
selection endをnew endに設定します。
start"の場合
selection startとselection endをstartに設定します。
end"の場合
selection startとselection endをnew endに設定します。
preserve"の場合
old lengthをendからstartを引いた値に設定します。
deltaをnew lengthからold lengthを引いた値に設定します。
selection startがendより大きい場合、それをdelta分だけ増やします。(deltaが負の場合、つまり新しいテキストが古いテキストより短い場合、selection startの値は減少します。)
それ以外の場合:selection startがstartより大きい場合、それをstartに設定します。(これにより、選択の開始位置が置き換えられた新しいテキストの開始位置にスナップされます。)
selection endがendより大きい場合、同じ方法でそれをdelta分だけ増やします。
それ以外の場合:selection endがstartより大きい場合、それをnew endに設定します。(これにより、選択の終了位置が置き換えられた新しいテキストの終了位置にスナップされます。)
選択範囲を設定します。この範囲は、selection startおよびselection endで設定されます。
setRangeText()
メソッドは次の列挙型を使用します。
enum SelectionMode {
" select " ,
" start " ,
" end " ,
" preserve " // デフォルト
};
現在選択されているテキストを取得するには、次のJavaScriptで十分です。
var selectionText = control. value. substring( control. selectionStart, control. selectionEnd);
テキストコントロールの先頭にテキストを追加し、テキスト選択を維持するには、 次の3つの属性を保存する必要があります。
var oldStart = control. selectionStart;
var oldEnd = control. selectionEnd;
var oldDirection = control. selectionDirection;
var prefix = "http://" ;
control. value = prefix + control. value;
control. setSelectionRange( oldStart + prefix. length, oldEnd + prefix. length, oldDirection);
送信可能な要素は、制約検証の候補ですが、条件によって制約検証から除外された場合を除きます。(たとえば、要素にdatalist要素の祖先がある場合、その要素は制約検証から除外されます。)
要素にはカスタム有効性エラーメッセージが定義されている場合があります。
初期状態では、要素のカスタム有効性エラーメッセージは空文字列に設定されている必要があります。値が空文字列でない場合、その要素はカスタムエラーが発生しているとみなされます。setCustomValidity()メソッドを使用して設定できますが、フォーム関連のカスタム要素を除きます。フォーム関連のカスタム要素には、そのElementInternalsオブジェクトのsetValidity()メソッドを介してカスタム有効性エラーメッセージを設定できます。
ユーザーエージェントは、コントロールの問題をユーザーに警告するときにカスタム有効性エラーメッセージを使用する必要があります。
要素はいくつかの方法で制約される可能性があります。以下は、フォームコントロールがある状態で、制約検証の目的でコントロールが無効になる有効性状態のリストです。(以下の定義は非規範的であり、各状態が適用されるかどうかをより正確に定義しているのは、この仕様書の他の部分です。)
コントロールが値を持たず、required属性を持っている場合(input required、textarea required)、またはラジオボタングループやselect要素においては、特定のセクションで指定されたより複雑なルールに従います。
setValidity()メソッドがvalueMissingフラグをtrueに設定した場合、フォーム関連のカスタム要素で発生します。
任意のユーザー入力を許可するコントロールの値が正しい構文ではない場合(メール、URL)。
setValidity()
メソッドがtypeMismatchフラグをフォーム関連のカスタム要素に対してtrueに設定する場合。
フォーム関連カスタム要素
setValidity()メソッドが、フォーム関連のカスタム要素に対してpatternMismatchフラグをtrueに設定する場合。
コントロールの値が、フォームコントロールのmaxlength属性に対して長すぎる場合(input maxlength、textarea maxlength)。
setValidity()メソッドが、フォーム関連のカスタム要素に対してtooLongフラグをtrueに設定する場合。
コントロールの値が、フォームコントロールのminlength属性に対して短すぎる場合(input minlength、textarea minlength)。
setValidity()メソッドが、フォーム関連のカスタム要素に対してtooShortフラグをtrueに設定する場合。
コントロールの値が空文字列ではなく、min属性に対して低すぎる場合。
setValidity()メソッドが、フォーム関連のカスタム要素に対してrangeUnderflowフラグをtrueに設定する場合。
コントロールの値が空文字列ではなく、max属性に対して高すぎる場合。
setValidity()メソッドが、フォーム関連のカスタム要素に対してrangeOverflowフラグをtrueに設定する場合。
コントロールの値が、step属性によって規定されたルールに適合しない場合。
setValidity()メソッドが、フォーム関連のカスタム要素に対してstepMismatchフラグをtrueに設定する場合。
コントロールに不完全な入力があり、ユーザーエージェントが現在の状態でフォームを送信できるとは思わない場合。
setValidity()メソッドが、フォーム関連のカスタム要素に対してbadInputフラグをtrueに設定する場合。
コントロールのカスタム有効性エラーメッセージ(要素のsetCustomValidity()メソッドまたはElementInternalsのsetValidity()メソッドによって設定されたもの)が空文字列でない場合。
要素が無効化されている場合でも、これらの状態が発生することがあります。そのため、フォームの送信中に検証を行ってもユーザーに問題を示さない場合でも、これらの状態はDOMで表現される可能性があります。
要素が上記のいずれの有効性状態にも該当しない場合、その要素は制約を満たしているとみなされます。
ユーザーエージェントがフォーム要素formの
静的な制約の検証を行う必要がある場合、次の手順を実行する必要があります。
これにより、(フォーム内のすべてのコントロールが有効であることを示す)ポジティブな結果または(無効なコントロールが存在することを示す)ネガティブな結果と、スクリプトが責任を負っていない無効な要素のリスト(場合によっては空のリスト)が返されます。
invalid controlsを、初期状態で空の要素リストとします。
controls内の各要素fieldについて、ツリー順で次の処理を行います。
もしinvalid controlsが空であれば、ポジティブな結果を返します。
unhandled invalid controlsを、初期状態で空の要素リストとします。
もしinvalid controlsに要素が存在する場合、その各要素fieldについて、ツリー順で次の処理を行います。
unhandled invalid controlsリスト内の要素のリストと共にネガティブな結果を返します。
ユーザーエージェントがフォーム要素formの
インタラクティブな制約の検証を行う場合、次の手順を実行する必要があります。
静的な制約の検証をformに対して行い、 もし結果がネガティブであった場合、unhandled invalid controlsを返されたリストとします。
もし結果がポジティブであれば、その結果を返します。
unhandled invalid controlsに含まれる少なくとも1つの要素に関連する制約の問題をユーザーに報告します。
ユーザーエージェントは、そのプロセスでこれらの要素の1つにフォーカスを当てることができます。その際、フォーカス手順を実行し、 ドキュメントのスクロール位置を変更したり、他の方法でユーザーの注意を引くために要素を表示します。 フォーム関連のカスタム要素の場合、これらのアクションのために検証アンカーを代わりに使用するべきです。
ユーザーエージェントは、複数の制約違反を報告することができます。
ユーザーエージェントは、関連する制約違反の報告を適切にまとめることができます(例:グループ内の複数のラジオボタンが必須とされている場合、1つのエラーのみ報告される必要があります)。
コントロールの1つがレンダリングされていない場合(例:属性が設定されている場合)、 ユーザーエージェントはスクリプトエラーを報告することができます。
ネガティブな結果を返します。
element.willValidate
HTMLObjectElement/willValidate
すべての現行エンジンでサポートされています。
フォームが送信される際に要素が検証される場合はtrueを返し、それ以外の場合はfalseを返します。
element.setCustomValidity(message)
HTMLObjectElement/setCustomValidity
すべての現行エンジンでサポートされています。
HTMLSelectElement/setCustomValidity
すべての現行エンジンでサポートされています。
カスタムエラーを設定し、要素が検証に失敗するようにします。指定されたメッセージは、問題をユーザーに報告する際に表示されるメッセージです。
引数が空の文字列である場合、カスタムエラーをクリアします。
element.validity.valueMissing
すべての現行エンジンでサポートされています。
要素に値がなく、必須フィールドである場合はtrueを返し、それ以外の場合はfalseを返します。
element.validity.typeMismatch
要素の値が正しい構文ではない場合はtrueを返し、それ以外の場合はfalseを返します。
element.validity.patternMismatch
要素の値が指定されたパターンと一致しない場合はtrueを返し、それ以外の場合はfalseを返します。
element.validity.tooLong
すべての現行エンジンでサポートされています。
要素の値が指定された最大長を超えている場合はtrueを返し、それ以外の場合はfalseを返します。
element.validity.tooShort
すべての現行エンジンでサポートされています。
要素の値が空文字列でない場合に、指定された最小長よりも短い場合はtrueを返し、それ以外の場合はfalseを返します。
element.validity.rangeUnderflow
要素の値が指定された最小値よりも低い場合はtrueを返し、それ以外の場合はfalseを返します。
element.validity.rangeOverflow
要素の値が指定された最大値よりも高い場合はtrueを返し、それ以外の場合はfalseを返します。
element.validity.stepMismatch
要素の値がstep属性によって指定されたルールに適合しない場合はtrueを返し、それ以外の場合はfalseを返します。
element.validity.badInput
すべての現行エンジンでサポートされています。
ユーザーインターフェイスでユーザーが入力した内容をユーザーエージェントが値に変換できない場合はtrueを返し、それ以外の場合はfalseを返します。
element.validity.customError
要素にカスタムエラーがある場合はtrueを返し、それ以外の場合はfalseを返します。
element.validity.valid
要素の値に検証の問題がない場合はtrueを返し、それ以外の場合はfalseを返します。
valid = element.checkValidity()
HTMLInputElement/checkValidity
すべての現行エンジンでサポートされています。
HTMLObjectElement/checkValidity
すべての現行エンジンでサポートされています。
HTMLSelectElement/checkValidity
すべての現行エンジンでサポートされています。
要素の値に検証の問題がない場合はtrueを返し、それ以外の場合はfalseを返し、その場合は要素でinvalidイベントが発火し、(イベントがキャンセルされていない場合)問題がユーザーに報告されます。
valid = element.reportValidity()
HTMLFormElement/reportValidity
すべての現行エンジンでサポートされています。
HTMLInputElement/reportValidity
すべての現行エンジンでサポートされています。
要素の値に検証の問題がない場合はtrueを返し、それ以外の場合はfalseを返し、その場合は要素でinvalidイベントが発火し、(イベントがキャンセルされていない場合)問題がユーザーに報告されます。
element.validationMessage
HTMLObjectElement/validationMessage
すべての現行エンジンでサポートされています。
要素の検証が行われる場合にユーザーに表示されるエラーメッセージを返します。
属性willValidateのgetterは、この要素が制約検証の候補である場合にtrueを返し、それ以外の場合はfalseを返さなければなりません(つまり、制約検証から除外されている場合はfalseを返します)。
すべての現在のエンジンでサポートされています。
属性willValidateのgetterは、ターゲット要素がフォーム関連カスタム要素でない場合、取得時に"NotSupportedError" DOMExceptionをスローしなければなりません。そうでない場合は、ターゲット要素が制約検証の候補である場合にtrueを返し、それ以外の場合はfalseを返さなければなりません。
HTMLInputElement/setCustomValidity
すべての現在のエンジンでサポートされています。
メソッドsetCustomValidity(error)のステップは次のとおりです:
errorに与えられた改行を正規化する結果を設定します。
カスタム有効性エラーメッセージにerrorを設定します。
次の例では、スクリプトがフォームコントロールの値を編集するたびにチェックし、無効な値の場合、setCustomValidity()メソッドを使用して適切なメッセージを設定します。
< label > Feeling: < input name = f type = "text" oninput = "check(this)" ></ label >
< script >
function check( input) {
if ( input. value == "good" ||
input. value == "fine" ||
input. value == "tired" ) {
input. setCustomValidity( '"' + input. value + '" is not a feeling.' );
} else {
// input is fine -- reset the error message
input. setCustomValidity( '' );
}
}
</ script >
すべての現在のエンジンでサポートされています。
属性validityのgetterは、この要素のValidityStateオブジェクトを返さなければなりません。このオブジェクトはこの要素の有効性状態を表します。このオブジェクトはライブです。
すべての現在のエンジンでサポートされています。
属性validityのgetterは、ターゲット要素がフォーム関連カスタム要素でない場合、取得時に"NotSupportedError" DOMExceptionをスローしなければなりません。そうでない場合は、ターゲット要素のValidityStateオブジェクトを返さなければなりません。このオブジェクトは有効性状態を表します。このオブジェクトはライブです。
[Exposed =Window ]
interface ValidityState {
readonly attribute boolean valueMissing ;
readonly attribute boolean typeMismatch ;
readonly attribute boolean patternMismatch ;
readonly attribute boolean tooLong ;
readonly attribute boolean tooShort ;
readonly attribute boolean rangeUnderflow ;
readonly attribute boolean rangeOverflow ;
readonly attribute boolean stepMismatch ;
readonly attribute boolean badInput ;
readonly attribute boolean customError ;
readonly attribute boolean valid ;
};
ValidityStateオブジェクトには、次の属性があります。取得時には、以下のリストで示された対応する条件がtrueであればtrueを返し、それ以外の場合はfalseを返す必要があります。
valueMissing
コントロールが欠損している場合です。
typeMismatch
すべての現在のエンジンでサポートされています。
コントロールが型不一致の問題がある場合です。
patternMismatch
すべての現在のエンジンでサポートされています。
コントロールがパターン不一致の問題がある場合です。
tooLong
コントロールが長すぎる場合です。
tooShort
コントロールが短すぎる場合です。
rangeUnderflow
すべての現在のエンジンでサポートされています。
コントロールがアンダーフローの問題がある場合です。
rangeOverflow
すべての現在のエンジンでサポートされています。
コントロールがオーバーフローの問題がある場合です。
stepMismatch
すべての現在のエンジンでサポートされています。
コントロールがステップ不一致の問題がある場合です。
badInput
コントロールが入力エラーがある場合です。
customError
コントロールがカスタムエラーがある場合です。
valid
他の条件のいずれもtrueではない場合です。
要素elementの有効性をチェックする手順は次の通りです。
もしelementが制約バリデーションの候補であり、その制約を満たしていない場合:
イベントを発生させ、そのイベント名をinvalidとし、elementでcancelable属性をtrueに設定する(ただし、キャンセルしても効果はありません)。
falseを返します。
trueを返します。
checkValidity()メソッドは、呼び出されたとき、この要素に対して有効性をチェックする手順を実行しなければなりません。
ElementInternals/checkValidity
すべての現在のエンジンでサポートされています。
checkValidity()メソッドは、ElementInternalsインターフェースの手順を実行しなければなりません。
elementを、このElementInternalsの対象要素に設定します。
もしelementがフォーム関連カスタム要素でない場合、"NotSupportedError"をスローし、DOMExceptionを生成します。
elementに対して有効性をチェックする手順を実行します。
要素elementの有効性を報告する手順は次の通りです。
もしelementが制約バリデーションの候補であり、その制約を満たしていない場合:
reportを、イベントを発生させた結果として取得し、イベント名をinvalidとし、elementでcancelable属性をtrueに設定します。
もしreportがtrueであれば、この要素の制約に関する問題をユーザーに報告します。制約に関する問題をユーザーに報告する際、ユーザーエージェントはelementに対してフォーカス手順を実行することができ、文書のスクロール位置を変更するか、またはelementをユーザーの注意を引くような形で表示するなどのアクションを実行することができます。もしelementが複数の問題を抱えている場合、ユーザーエージェントは複数の制約違反を報告することができます。
falseを返します。
trueを返します。
reportValidity()メソッドは、呼び出されたとき、この要素に対して有効性を報告する手順を実行しなければなりません。
ElementInternals/reportValidity
すべての現在のエンジンでサポートされています。
reportValidity()メソッドは、ElementInternalsインターフェースの手順を実行しなければなりません。
elementを、このElementInternalsの対象要素に設定します。
もしelementがフォーム関連カスタム要素でない場合、"NotSupportedError"をスローし、DOMExceptionを生成します。
elementに対して有効性を報告する手順を実行します。
validationMessage属性のゲッターは、次の手順を実行する必要があります。
この要素が制約バリデーションの候補でない場合、またはこの要素がその制約を満たしている場合、空の文字列を返します。
ユーザーエージェントが、制約違反がある唯一のフォームコントロールである場合にユーザーに表示する適切にローカライズされたメッセージを返します。ユーザーエージェントがそのような状況で実際にテキストメッセージを表示しない場合(例えば、グラフィカルなキューを表示する場合など)、コントロールが満たしていない制約を表す適切にローカライズされたメッセージを返します。要素が制約バリデーションの候補であり、カスタムエラーの問題がある場合、カスタムバリディティエラーメッセージが返される値に含まれている必要があります。
サーバーはクライアントサイドのバリデーションに依存してはいけません。クライアントサイドのバリデーションは、悪意のあるユーザーによって意図的に無効化されたり、古いユーザーエージェントやこれらの機能を実装していない自動化ツールを使用するユーザーによって意図せず無効化される可能性があります。制約バリデーション機能は、あくまでユーザーエクスペリエンスを向上させるためのものであり、セキュリティメカニズムを提供するものではありません。
このセクションは規範的ではありません。
フォームが送信されると、フォーム内のデータはenctypeによって指定された構造に変換され、指定されたアクションに対して、指定されたメソッドを使用して送信されます。
たとえば、次のフォームを考えてみましょう。
< form action = "/find.cgi" method = get >
< input type = text name = t >
< input type = search name = q >
< input type = submit >
</ form >
ユーザーが最初のフィールドに「cats」、2番目のフィールドに「fur」と入力し、送信ボタンを押した場合、ユーザーエージェントは/find.cgi?t=cats&q=furを読み込みます。
一方、次のフォームを考えてみてください。
< form action = "/find.cgi" method = post enctype = "multipart/form-data" >
< input type = text name = t >
< input type = search name = q >
< input type = submit >
</ form >
同じユーザー入力を与えた場合、送信時の結果はかなり異なります。ユーザーエージェントは指定されたURLに対してHTTP POSTを実行し、エンティティボディには次のようなテキストが含まれます。
------kYFrd4jNJEgCervE Content-Disposition: form-data; name="t" cats ------kYFrd4jNJEgCervE Content-Disposition: form-data; name="q" fur ------kYFrd4jNJEgCervE--
フォーム要素のデフォルトボタンとは、そのフォーム所有者がそのフォーム要素である、送信ボタンのうち、ツリー順で最初のボタンを指します。
ユーザーエージェントがユーザーにフォームを暗黙的に送信させることをサポートしている場合(例えば、いくつかのプラットフォームでは、テキストコントロールがフォーカスされている間に「Enter」キーを押すと暗黙的にフォームが送信される場合があります)、デフォルトボタンがアクティベーション動作を持ち、無効でないフォームの場合、ユーザーエージェントはそのデフォルトボタンにクリックイベントを発火させなければなりません。
ウェブ上には、暗黙的にフォームを送信する方法がないと利用できないページが存在するため、ユーザーエージェントはこれをサポートすることが強く推奨されます。
フォームに送信ボタンがない場合、暗黙の送信メカニズムは次の手順を実行しなければなりません:
フォームに複数の暗黙の送信をブロックするフィールドがある場合、終了します。
前段の目的のために、ある要素がフォーム要素の暗黙の送信をブロックするフィールドである場合、それはそのフォーム所有者がそのフォーム要素であり、タイプ属性が以下のいずれかの状態にあるinput要素です: テキスト、検索、電話、URL、メール、パスワード、日付、月、週、時間、ローカル日付と時間、数値
各 form
要素には、エントリリストを構築中というブール値があり、初期値はfalseです。
各 form
要素には、送信イベントを発生させるというブール値があり、初期値はfalseです。
フォームを送信するには、form要素formを、オプションのブール値submit()メソッドから送信された(デフォルトはfalse)およびオプションのユーザーのナビゲーション関与 userInvolvement(デフォルトは"none")を与えられた状態で、要素submitter(通常はボタン)から送信します。
もし form が ナビゲートできない 場合、リターンします。
もし form の エントリリストを構築中 がtrueの場合、リターンします。
form document を form の ノードドキュメントとします。
もし form document の アクティブサンドボックスフラグセット が サンドボックスフォームブラウジングコンテキストフラグ を持っている場合、リターンします。
もし submitted from submit()
メソッド がfalseである場合は、以下の手順を実行します:
もし form の 送信イベントを発生させる がtrueである場合、リターンします。
form の 送信イベントを発生させる をtrueに設定します。
form の フォーム所有者 が form である 送信可能な要素 のリスト内の各要素 field に対して、field の ユーザーの有効性 をtrueに設定します。
もし submitter 要素の ノーバリデート状態 がfalseである場合、form の制約を対話的に検証するを実行し、結果を確認します。結果が負の場合(つまり、制約の検証で無効なフィールドがあると判断され、おそらくユーザーに通知された)、以下の手順を実行します:
form の 送信イベントを発生させる をfalseに設定します。
リターンします。
submitterButton を submitter が form の場合はnullに設定します。それ以外の場合、submitterButton を submitter に設定します。
shouldContinue を イベントを発火 させ、submit イベントを
form で発火させ、SubmitEvent
を使用し、submitter
属性を submitterButton に初期化し、bubbles
属性をtrueに、cancelable
属性をtrueに初期化します。
form の 送信イベントを発生させる をfalseに設定します。
もし shouldContinue がfalseであれば、リターンします。
もし form が ナビゲートできない 場合、リターンします。
ナビゲートできない
が再度実行されるのは、submit
イベントをディスパッチすることが結果を変えた可能性があるためです。
encoding をフォームのエンコーディングを選択する の結果とします。
entry list を エントリリストを構築する の結果とし、 form、submitter、および encoding を使用します。
アサート: entry list がnullでないことを確認します。
もし form が ナビゲートできない 場合、リターンします。
ナビゲートできない
が再度実行されるのは、formdata
イベントを エントリリストを構築する
ときにディスパッチすることで結果が変わった可能性があるためです。
method を submitter 要素の メソッド とします。
もし method が ダイアログ の場合は:
action を submitter 要素の アクション とします。
もし action が空文字列であれば、action を URL とし、form document とします。
parsed action をURLのエンコーディング解析 の結果とし、 action を submitter の ノードドキュメント に対して相対的に解析します。
もし parsed action が失敗した場合、リターンします。
scheme を スキーム とし、 parsed action を scheme とします。
enctype を submitter 要素の エンコードタイプ とします。
formTarget をnullとします。
もし submitter 要素が 送信ボタン であり、その formtarget
属性を持っている場合、
formTarget にその formtarget
属性値を設定します。
target を要素のターゲットを取得する の結果とし、 submitter の フォーム所有者 および formTarget を取得します。
noopener を要素のnoopenerを取得する の結果とし、form および target を取得します。
targetNavigable を、 ナビゲーブルを選択するルール を適用し、target、form の ノードナビゲーブル で、 noopener とします。
もし targetNavigable がnullであれば、リターンします。
historyHandling を "auto"
とします。
もし form document が targetNavigable の アクティブドキュメント と等しく、
form document がまだ 完全に読み込まれていない 場合、
historyHandling を "置き換え"
に設定します。
以下の表に基づいて scheme に該当する行を選択します。次に、その行に基づいて method を選択し、各列に基づいて適切なセルを選択します。その後、そのセルに名前が記載されている手順にジャンプし、下に定義されている手順に従います。
| GET | POST | |
|---|---|---|
http
| アクションURLを変更する | エンティティボディとして送信する |
https
| アクションURLを変更する | エンティティボディとして送信する |
ftp
| アクションURLを取得する | アクションURLを取得する |
javascript
| アクションURLを取得する | アクションURLを取得する |
data
| アクションURLを変更する | アクションURLを取得する |
mailto
| ヘッダー付きで送信する | 本文として送信する |
もし scheme がこの表に記載されていないものであれば、この仕様ではその動作は定義されていません。ユーザーエージェントは、別の仕様が定義されていない場合、類似のスキームに対してこの仕様で定義されたものと類似の方法で動作するべきです。
各 form
要素には 計画されたナビゲーション があり、nullまたは タスク のどちらかです。form
が最初に作成されたとき、その 計画されたナビゲーション
はnullに設定されます。以下に示す動作では、ユーザーエージェントが指定されたURLに ナビゲートを計画する
必要がある場合には、次の手順を実行します。
referrerPolicy を空の文字列に設定します。
もし form
要素のリンクタイプに noreferrer
キーワードが含まれている場合、referrerPolicy を "no-referrer" に設定します。
もし form
に非nullの 計画されたナビゲーション がある場合、それをその タスクキュー から削除します。
要素タスクをキューに追加する を DOM操作タスクソース に与え、form
要素および次の手順を実行します:
form
の計画されたナビゲーション をnullに設定します。
ナビゲートする
targetNavigable に url を使用し、form
要素の ノードドキュメント とし、historyHandling を
historyHandling に設定し、userInvolvement を
userInvolvement に設定し、referrerPolicy を
referrerPolicy に設定し、documentResource を postResource
に設定し、formDataEntryList を entry
list に設定します。
form
の計画されたナビゲーション
を、今追加された タスク に設定します。
以下の動作は次の通りです:
pairs を名前と値のペアのリストに変換する の結果とし、entry list を使用します。
query をapplication/x-www-form-urlencoded
シリアライザー の結果とし、pairs と encoding を使用します。
parsed action のクエリ コンポーネントを query に設定します。
ナビゲートを計画する を parsed action に対して実行します。
アサート: method は POST であることを確認します。
enctype に基づいて次の手順を実行します:
application/x-www-form-urlencoded
pairs を名前と値のペアのリストに変換する の結果とし、entry list を使用します。
body をapplication/x-www-form-urlencoded
シリアライザー の結果とし、pairs と encoding を使用します。
body をエンコード の結果とし、body をエンコードします。
mimeType を `application/x-www-form-urlencoded`
に設定します。
multipart/form-data
body をmultipart/form-data
エンコードアルゴリズム の結果とし、entry list と encoding を使用します。
mimeType を等形エンコード の結果として
"multipart/form-data; boundary=" を結合し、multipart/form-data
境界文字列 をmultipart/form-data
エンコードアルゴリズム で生成します。
text/plain
pairs を名前と値のペアのリストに変換する の結果とし、entry list を使用します。
body をtext/plain
エンコードアルゴリズム の結果とし、pairs を使用します。
body をエンコード の結果として、encoding を使用して body をエンコードします。
mimeType を `text/plain`
に設定します。
ナビゲートを計画する を parsed action に対して実行し、POST リソース の リクエストボディ を body とし、リクエストコンテンツタイプ を mimeType に設定します。
ナビゲートを計画する を parsed action に対して実行します。
entry list は破棄されます。
pairs を名前と値のペアのリストに変換する の結果とし、entry list を使用します。
headers をapplication/x-www-form-urlencoded
シリアライザー の結果とし、pairs と encoding を使用します。
headers 内の U+002B プラス記号(+)を "%20" という文字列に置き換えます。
parsed action のクエリ を headers に設定します。
ナビゲートを計画する を parsed action に対して実行します。
pairs を名前と値のペアのリストに変換する の結果とし、entry list を使用します。
enctype に基づいて次の手順を実行します:
text/plain
body をtext/plain
エンコードアルゴリズム の結果とし、pairs を使用します。
body をUTF-8パーセントエンコード の結果として実行し、body をデフォルトエンコードセット を使用してエンコードします。 [URL]
body をapplication/x-www-form-urlencoded
シリアライザー の結果とし、pairs と encoding を使用します。
もし parsed action のクエリ がnullであれば、 空の文字列に設定します。
もし parsed action のクエリ が空でない場合、単一のU+0026 アンパサンド文字(&)を追加します。
parsed action のクエリ に
"body=" を追加します。
body を parsed action のクエリ に追加します。
ナビゲートを計画する を parsed action に対して実行します。
エントリリストは、通常フォームの内容を表すリストです。エントリは、名前(スカラー値文字列)と値(スカラー値文字列またはファイルオブジェクトのいずれか)のタプルで構成されます。
エントリを作成するには、文字列name、文字列またはBlobオブジェクトvalue、およびオプションでスカラー値文字列のfilenameを指定します。
その他の場合:
valueがファイルオブジェクトでない場合、valueを新しいファイルオブジェクトに設定し、同じバイトを表現し、名前属性値を「blob」にします。
filenameが指定されている場合、valueを新しいファイルオブジェクトに設定し、同じバイトを表現し、名前属性をfilenameに設定します。
これらの操作は、新しいファイルオブジェクトを作成します。filenameが指定されている場合、または渡されたBlobがファイルオブジェクトでない場合です。その場合、渡されたBlobオブジェクトの識別性は保持されません。
エントリリストの構築は、form、オプションでsubmitter(デフォルトはnull)、およびオプションでencoding(デフォルトはUTF-8)を指定して実行します。
formのエントリリストの構築がtrueである場合、nullを返します。
formのエントリリストの構築をtrueに設定します。
entry listを新しい空のエントリリストに設定します。
各field要素について、controls内で、ツリー順序で:
以下のいずれかが真である場合:
fieldがdatalist要素の祖先を持つ場合;
fieldが無効である場合;
fieldがボタンであるが、submitterではない場合;
fieldがinput要素であり、そのtype属性がチェックボックス状態にあり、チェックされていない場合;
fieldがinput要素であり、そのtype属性がラジオボタン状態にあり、チェックされていない場合,
次に進みます(continue)。
fieldがフォーム関連カスタム要素の場合、fieldとentry listを指定してエントリ構築アルゴリズムを実行し、その後で次に進みます(continue)。
field要素にname属性が指定されていない場合、またはそのname属性の値が空である場合、次に進みます(continue)。
nameをfield要素のname属性の値に設定します。
field要素がselect要素である場合、そのselect要素内のオプションリストの中で、選択されている状態であり、無効でないエントリを作成するにはnameとoption要素の値を使用し、それをentry listに追加します。
それ以外の場合、field要素がinput要素であり、そのtype属性がチェックボックス状態またはラジオボタン状態にある場合:
それ以外の場合、field要素がinput要素であり、そのtype属性がファイルアップロード状態にある場合:
それ以外の場合、field要素がinput要素であり、そのtype属性が状態にあり、nameがASCIIケース非感受性で「_charset_」と一致する場合:
要素にdirname属性があり、その属性の値が空でなく、要素が自動方向性フォーム関連要素である場合:
form dataを新しいFormDataオブジェクトに設定し、entry
listに関連付けます。
イベントをformdataとしてformに発生させ、FormDataEventを使用し、formData属性をform
dataに初期化し、bubbles属性をtrueに初期化します。
formのエントリリストの構築をfalseに設定します。
entry listのクローンを返します。
ユーザーエージェントがフォームのエンコーディングを選択する場合、次の手順を実行しなければなりません:
encodingを文書の文字エンコーディングに設定します。
もしform要素がaccept-charset属性を持っている場合は、次のサブステップを実行しencodingを設定します:
inputをform要素のaccept-charset属性の値に設定します。
candidate encoding labelsを、inputをASCIIの空白文字で分割した結果に設定します。
candidate encodingsを空の文字エンコーディングのリストとして設定します。
candidate encoding labelsの各トークンについて順に(inputで見つかった順に)、そのトークンに対してエンコーディングを取得し、それが失敗しない場合はcandidate encodingsにエンコーディングを追加します。
もしcandidate encodingsが空の場合は、UTF-8を返します。
candidate encodingsの最初のエンコーディングを返します。
出力エンコーディングを取得してencodingを返します。
application/x-www-form-urlencodedやtext/plainエンコーディングアルゴリズムは、値が文字列である名前と値のペアのリストを取ります。これは、値がファイルオブジェクトである可能性のあるエントリーリストとは異なります。以下のアルゴリズムは、その変換を行います。
エントリーリストentry listを名前と値のペアのリストに変換するには、次の手順を実行します:
listを空の名前と値のペアのリストとして設定します。
各entryについてentry listを次のように実行します:
nameをentryのnameとし、U+000D (CR) が後に U+000A (LF) を伴わないすべての出現、およびU+000A (LF) が前に U+000D (CR) を伴わないすべての出現を、U+000D (CR) および U+000A (LF) からなる文字列に置き換えます。
もしentryのvalueがファイルオブジェクトである場合、valueをentryのvalueの名前に設定します。それ以外の場合は、valueをentryのvalueに設定します。
value内のU+000D (CR) が後に U+000A (LF) を伴わないすべての出現、およびU+000A (LF) が前に U+000D (CR) を伴わないすべての出現を、U+000D (CR) および U+000A (LF) からなる文字列に置き換えます。
新しい名前と値のペアをlistに追加し、その名前をname、値をvalueとします。
listを返します。
詳細はURLに記載されています。application/x-www-form-urlencodedに関する詳細は、[URL]を参照してください。
multipart/form-dataエンコーディングアルゴリズムは、エントリーリスト entry listとエンコーディング
encodingを与えられた場合に、以下のように動作します:
各 entry について entry listを次のように実行します:
entryの名前において、U+000D (CR) が後に U+000A (LF) を伴わないすべての出現、およびU+000A (LF) が前に U+000D (CR) を伴わないすべての出現を、U+000D (CR) および U+000A (LF) からなる文字列に置き換えます。
もしentryの値がファイルオブジェクトでない場合、entryの値において、U+000D (CR) が後に
U+000A (LF) を伴わないすべての出現、およびU+000A (LF) が前に U+000D (CR) を伴わないすべての出現を、U+000D (CR) および U+000A (LF)
からなる文字列に置き換えます。
このアルゴリズムの返り値を生成する際に使用されるバイト列は、RFC 7578に記載されている規則に従ってentry
listをエンコードした結果のバイト列です。フォームからの値の返却: multipart/form-dataの条件を考慮して[RFC7578]を参照してください。
entry list内の各エントリーはフィールドであり、そのエントリーの名前はフィールド名であり、値はフィールド値です。
パートの順序は、entry list内のフィールドの順序と同じでなければなりません。同じ名前の複数のエントリーは、異なるフィールドとして扱わなければなりません。
生成されたmultipart/form-dataリソースのフィールド名、非ファイルフィールドのフィールド値、およびファイルフィールドのファイル名は、対応するエントリーの名前または値をencodingを使用してエンコードし、バイト列に変換した結果に設定されなければなりません。
フィールド名およびファイルフィールドのファイル名については、前述のエンコードの結果をエスケープし、0x0A (LF) バイトを `%0A` のバイト列に、0x0D
(CR) を `%0D` に、0x22 (") を `%22`
に置き換えなければなりません。ユーザーエージェントは他のエスケープを行ってはなりません。
生成されたmultipart/form-dataリソースの非ファイルフィールドに対応するパートには、`Content-Type`ヘッダーを指定してはなりません。
このアルゴリズムの返り値を生成する際にユーザーエージェントが使用する境界はmultipart/form-data境界文字列です。(この値は、このアルゴリズムによって生成されたフォーム送信ペイロードのMIMEタイプを生成するために使用されます。)
multipart/form-data ペイロードの解釈方法の詳細は、RFC 7578を参照してください。[RFC7578]
text/plainエンコーディングアルゴリズムは、名前と値のペアpairsのリストを与えられた場合、次のように動作します:
resultを空の文字列とします。
pairs内の各pairについて:
pairの名前をresultに追加します。
単一のU+003D等号(=)をresultに追加します。
pairの値をresultに追加します。
U+000D CARRIAGE RETURN (CR) U+000A LINE FEED (LF)の文字ペアをresultに追加します。
resultを返します。
text/plainフォーマットを使用するペイロードは、人間が読めるように設計されています。しかし、フォーマットに曖昧さがあるため(たとえば、値の中のリテラルの改行と、値の終わりの改行を区別する方法がない)、コンピュータによって確実に解釈されることはありません。
SubmitEvent インターフェースすべての最新エンジンでサポートされています。
すべての最新エンジンでサポートされています。
[Exposed =Window ]
interface SubmitEvent : Event {
constructor (DOMString type , optional SubmitEventInit eventInitDict = {});
readonly attribute HTMLElement ? submitter ;
};
dictionary SubmitEventInit : EventInit {
HTMLElement ? submitter = null ;
};
submitter属性は、初期化された値を返す必要があります。
FormDataEvent
インターフェースすべての最新エンジンでサポートされています。
すべての最新エンジンでサポートされています。
[Exposed =Window ]
interface FormDataEvent : Event {
constructor (DOMString type , FormDataEventInit eventInitDict );
readonly attribute FormData formData ;
};
dictionary FormDataEventInit : EventInit {
required FormData formData ;
};
event.formData
FormData
オブジェクトを返し、ターゲットの フォーム
に関連付けられた要素の名前と値を表します。FormData
オブジェクトに対する操作は、送信されるフォームデータに影響を与えます。
formData
属性は、初期化された値を返す必要があります。それは、FormData
オブジェクトを表し、エントリーリストに関連付けられています。これは、フォームデータセットの構築が行われるときに構築され、フォーム
が送信されるときに発生します。
フォーム要素
formがリセットされるとき、次の手順を実行します:
resetを、formでresetという名前のイベントを発火させた結果とします。このイベントは、bubbles
とcancelable
属性がtrueに初期化された状態で発火されます。
もしresetがtrueであれば、formのフォームオーナーがformである各リセット可能な要素のリセットアルゴリズムを呼び出します。
各リセット可能な要素は、それぞれのリセットアルゴリズムを定義します。これらのアルゴリズムの一部としてフォームコントロールに加えられる変更は、ユーザーによる変更とは見なされません(たとえば、これによりinputイベントが発火することはありません)。
details
要素すべての現在のエンジンでサポートされています。
すべての現在のエンジンでサポートされています。
summary要素が続くフローコンテンツ。
name — グループの名前。details要素
open — 詳細が表示されているかどうか
[Exposed =Window ]
interface HTMLDetailsElement : HTMLElement {
[HTMLConstructor ] constructor ();
[CEReactions ] attribute DOMString name ;
[CEReactions ] attribute boolean open ;
};
details要素は、ユーザーが追加情報や操作を取得できるディスクロージャーウィジェットを表します。
すべてのHTML要素と同様に、details要素を使用して別の種類のコントロールを表すことは準拠していません。例えば、タブウィジェットやメニューウィジェットはディスクロージャーウィジェットではないため、details要素を使用してこれらのパターンを実装するのは誤りです。
details要素は脚注には適していません。脚注のマークアップについては脚注セクションを参照してください。
要素の最初のsummary要素の子が存在する場合は、その子要素が詳細の要約または説明を表します。子要素が存在しない場合、ユーザーエージェントは独自の説明(例:"Details")を提供するべきです。
要素の残りの内容は、追加情報またはコントロールを表します。
name属性は、関連するdetails要素のグループの名前を指定します。このグループの一つの要素が開くと、他の要素は閉じます。属性が指定されている場合、その値は空の文字列であってはなりません。
この機能を使用する前に、著者は関連するdetails要素を排他的アコーディオンにまとめることがユーザーにとって有益かどうかを検討する必要があります。排他的アコーディオンを使用することで、コンテンツセットが占める最大スペースを削減できる可能性がありますが、多くの項目を開く必要があるユーザーや、複数の項目の内容を同時に確認したいユーザーにとっては、苛立たしいものとなる可能性があります。
文書には、details要素が同じdetails名グループ内でopen属性を持つ要素が複数含まれていてはなりません。著者は、スクリプトを使用してdetails要素を文書に追加し、それによってdetails名グループにopen属性を持つ要素が複数含まれるようにしてはなりません。
共通のname属性によって作成される要素のグループは排他的であり、最大で1つのdetails要素しか開くことができません。この排他性はユーザーエージェントによって強制され、結果として強制がマークアップ内のopen属性を直ちに変更します。この著者に対する要件は、誤解を招くようなマークアップを禁止します。
文書には、同じdetails名グループ内に別のdetails要素が含まれているdetails要素が含まれていてはなりません。
name属性を使用して複数の関連するdetails要素をグループ化する文書は、これらの関連要素を1つの包含要素(section要素やarticle要素など)にまとめて配置する必要があります。グループに見出しを付けるのが適切な場合は、著者はその見出しを包含要素の先頭にある見出し要素に配置するべきです。
関連する要素を視覚的およびプログラム的にグループ化することは、アクセシブルなユーザー体験にとって重要な場合があります。これにより、ユーザーはこれらの要素間の関係を理解しやすくなります。関連する要素がウェブページの別々のセクションに配置されている場合、それらの要素間の関係は発見しにくく、理解しにくくなる可能性があります。
open属性はブール属性です。指定されている場合、要約と追加情報の両方がユーザーに表示されることを示します。属性が存在しない場合、要約のみが表示されます。
要素が作成されたときに、属性が存在しない場合は追加情報が非表示にされるべきです。属性が存在する場合、その情報が表示されるべきです。その後、属性が削除された場合は情報が非表示にされるべきであり、属性が追加された場合は情報が表示されるべきです。
ユーザーエージェントは、ユーザーが追加情報を表示または非表示にするよう要求できるようにするべきです。詳細を表示する要求を尊重するために、ユーザーエージェントは要素に対して設定を行い、open属性を空の文字列にします。情報を非表示にする要求を尊重するために、ユーザーエージェントは要素からopen属性を削除しなければなりません。
追加情報を表示または非表示にする機能は、適切なsummary要素が存在する場合、その要素のアクティベーション動作である可能性があります。しかし、そのような要素が存在しない場合でも、ユーザーエージェントは他のユーザーインターフェースの手段を通じてこの機能を提供できるでしょう。
details名グループにはdetails要素aが含まれており、その中には次のすべての条件を満たす他のdetails要素bも含まれています:
すべてのdetails要素にはdetailsトグルタスクトラッカーがあり、これはトグルタスクトラッカーまたはnullであり、最初はnullです。
次の属性変更手順は、要素、localName、oldValue、value、およびnamespaceを考慮してすべてのdetails要素に対して使用されます:
namespaceがnullでない場合は、終了します。
localNameがnameである場合、要素を指定して必要に応じて指定された要素を閉じることによるdetailsの排他性を確保します。
localNameがopenである場合:
oldValueまたはvalueの一方がnullで、他方がnullでない場合、このdetails要素に対してdetails通知タスク手順として知られる次の手順を実行します:
open属性が連続して切り替えられると、結果としてタスクが本質的に統合され、イベントが1つだけ発生します。
oldValueがnullである場合、このdetails要素を指定してdetailsトグルイベントタスクをキューに追加し、"閉じた"と"開いた"を指定します。
それ以外の場合、このdetails要素を指定してdetailsトグルイベントタスクをキューに追加し、"開いた"と"閉じた"を指定します。
oldValueがnullであり、valueがnullでない場合、要素を指定して必要に応じて他の要素を閉じることによるdetailsの排他性を確保します。
detailsのHTML要素挿入手順は、insertedNodeを指定して次の通りです:
insertedNodeを指定して、必要に応じて指定された要素を閉じることによるdetailsの排他性を確保します。
明確にするために、これらの属性変更と挿入手順は、パーサーを介して属性や要素が挿入された場合にも実行されます。
detailsトグルイベントタスクをキューに追加するには、details要素element、文字列oldState、および文字列newStateを指定します:
elementのdetailsトグルタスクトラッカーがnullでない場合:
oldStateをelementのdetailsトグルタスクトラッカーの旧状態に設定します。
elementのdetailsトグルタスクトラッカーのタスクをタスクキューから削除します。
elementのdetailsトグルタスクトラッカーをnullに設定します。
elementを指定して、要素タスクをキューに追加し、DOM操作タスクソースを指定して次の手順を実行します:
oldStateを初期化し、旧状態と新状態の属性を持つToggleEventを使用してelementでイベントを発火します。
elementのdetailsトグルタスクトラッカーをnullに設定します。
elementのdetailsトグルタスクトラッカーを、直前にキューに追加されたタスクを設定し、旧状態に設定された構造体に設定します。
必要に応じて他の要素を閉じることによるdetailsの排他性を確保するには、details要素elementを指定します:
documentをelementのノード文書とします。
documentの突然変異イベントフラグを発火するの値をoldFlagとします。
documentの突然変異イベントフラグを発火するをfalseに設定します。
groupMembersを、ツリー順でelementのdetails名グループに含まれる、element以外のすべての要素を含むリストとします。
groupMembersの各要素otherElementに対して、次の操作を行います:
documentの突然変異イベントフラグを発火するをoldFlagに設定します。
必要に応じて指定された要素を閉じることによるdetailsの排他性を確保するには、details要素elementを指定します:
elementがopen属性を持っていない場合、終了します。
documentをelementのノード文書とします。
documentの突然変異イベントフラグを発火するの値をoldFlagとします。
documentの突然変異イベントフラグを発火するをfalseに設定します。
groupMembersを、ツリー順でelementのdetails名グループに含まれる、element以外のすべての要素を含むリストとします。
groupMembersの各要素otherElementに対して、次の操作を行います:
documentの突然変異イベントフラグを発火するをoldFlagに設定します。
すべての現在のエンジンでサポートされています。
nameおよびopenIDL属性は、同名のそれぞれのコンテンツ属性を反映する必要があります。
祖先のdetailsを明らかにするアルゴリズムは、currentNodeに対して次の手順を実行します:
currentNodeがフラットツリー内で親ノードを持つ間:
次の例は、進行状況レポートで技術的な詳細を隠すためにdetails要素が使用される例を示しています。
< section class = "progress window" >
< h1 > 「本当にあなたの子供の夢を実現する」コピー</ h1 >
< details >
< summary > コピー中... < progress max = "375505392" value = "97543282" ></ progress > 25%</ summary >
< dl >
< dt > 転送速度:</ dt > < dd > 452KB/s</ dd >
< dt > ローカルファイル名:</ dt > < dd > /home/rpausch/raycd.m4v</ dd >
< dt > リモートファイル名:</ dt > < dd > /var/www/lectures/raycd.m4v</ dd >
< dt > 所要時間:</ dt > < dd > 01:16:27</ dd >
< dt > カラープロファイル:</ dt > < dd > SD (6-1-6)</ dd >
< dt > 寸法:</ dt > < dd > 320×240</ dd >
</ dl >
</ details >
</ section >
次の例は、details要素が、デフォルトで一部のコントロールを非表示にする方法を示しています:
< details >
< summary >< label for = fn > 名前と拡張子:</ label ></ summary >
< p >< input type = text id = fn name = fn value = "Pillar Magazine.pdf" >
</ p >
< p >< label >< input type = checkbox name = ext checked > 拡張子を隠す</ label >
</ details >
これを他のdetails要素と組み合わせて使用し、リスト内の一連のフィールドを小さな見出しセットに折りたたみ、各フィールドを開くことができるようにすることができます。


これらの例では、要約は実際の値ではなく、コントロールが変更できる内容のみを要約しています。これは理想的ではありません。
次の例は、name属性を使用して、ユーザーが1つのdetails要素を開くアクションを実行すると、開いている他のdetails要素が閉じるようにする排他的アコーディオンを作成する例です。
< section class = "characteristics" >
< details name = "frame-characteristics" >
< summary > 材料</ summary >
額縁はオーク材の無垢材で作られています。
</ details >
< details name = "frame-characteristics" >
< summary > サイズ</ summary >
額縁は高さ40cm、幅30cmの写真が収まります。
額縁の高さは45cm、幅35cm、厚さ2cmです。
</ details >
</ details name = "frame-characteristics" >
< summary > 色</ summary >
額縁はそのままの木の色、または黒染めで利用可能です。
</ details >
</ section >
次の例は、排他的アコーディオンを作成するためにname属性を使用している要素のセットの一部であるdetails要素にopen属性が設定されている場合に何が起こるかを示しています。
最初のマークアップが以下の場合:
< section class = "characteristics" >
< details name = "frame-characteristics" id = "d1" open > ...</ details >
< details name = "frame-characteristics" id = "d2" > ...</ details >
</ details name = "frame-characteristics" id = "d3" > ...</ details >
</ section >
スクリプトが次のように実行されると:
document. getElementById( "d2" ). setAttribute( "open" , "" );
スクリプトが実行された後のツリーは次のマークアップと同等になります:
< section class = "characteristics" >
< details name = "frame-characteristics" id = "d1" > ...</ details >
< details name = "frame-characteristics" id = "d2" open > ...</ details >
</ details name = "frame-characteristics" id = "d3" > ...</ details >
</ section >
なぜなら、open属性をd2に設定すると、それがd1から削除されるためです。
同じことが、d2内のsummary要素をユーザーがアクティブ化した場合にも発生します。
open属性は、ユーザーがコントロールと対話する際に自動的に追加および削除されるため、その状態に基づいて要素を異なるスタイルにするためにCSSで使用できます。ここでは、スタイルシートを使用して、要素が開かれたり閉じられたりしたときにsummaryの色をアニメーション化します:
< style >
details > summary { transition : color 1 s ; color : black ; }
details [ open ] > summary { color : red ; }
</ style >
< details >
< summary > 自動ステータス: 動作中</ summary >
< p > 速度: 12m/s</ p >
</ p > 方向: 北</ p >
</ details >
summary要素すべての現在のエンジンでサポートされています。
details要素の一部として使用されます。
HTMLElementを使用します。
summary要素は、その親のdetails要素(存在する場合)内の他の内容の要約、キャプション、または凡例を表します。
summary要素は、次のアルゴリズムがtrueを返す場合に、親detailsの要約です:
このsummary要素に親がいない場合、falseを返します。
parentをこのsummary要素の親に設定します。
parentがdetails要素でない場合、falseを返します。
trueを返します。
summary要素のアクティベーション動作は、次の手順を実行します:
このsummary要素が親detailsの要約でない場合、終了します。
parentをこのsummary要素の親に設定します。
もしparentにopen属性が存在する場合、それを削除します。それ以外の場合、parentのopen属性を空の文字列で設定します。
これにより、details通知タスク手順が実行されます。
コマンドは、メニュー項目、ボタン、およびリンクの背後にある抽象概念です。コマンドが定義されると、インターフェイスの他の部分は同じコマンドを参照できるようになり、多くのアクセスポイントが無効状態などのファセットを共有できます。
コマンドには、次のファセットが定義されています:
ユーザーエージェントは、次の条件を満たすコマンドをUIに公開する場合があります:
ユーザーエージェントは、特にアクセスキーを持つコマンドについて、これを実行し、そのキーをユーザーに宣伝することが奨励されています。
たとえば、このようなコマンドは、ユーザーエージェントのメニューバーに一覧表示される可能性があります。
a要素を使用してコマンドを定義する
a要素がhref属性を持つ場合、それはコマンドを定義します。
コマンドのラベルは、その要素の子孫テキストコンテンツです。
コマンドのアクセスキーは、その要素の割り当てられたアクセスキー(存在する場合)です。
コマンドのは、その要素に属性がある場合はtrue(非表示)、それ以外の場合はfalseです。
コマンドの無効状態ファセットは、その要素またはその祖先の一つがinertである場合はtrue、それ以外の場合はfalseです。
コマンドのアクションは、要素に対してclickイベントを発火させることです。
button要素を使用してコマンドを定義する
コマンドのラベル、アクセスキー、、およびアクションファセットは、a要素の場合と同様に決定されます(前のセクションを参照)。
コマンドの無効状態は、その要素またはその祖先の一つがinertである場合、または要素の無効状態が設定されている場合にtrueとなり、それ以外の場合はfalseです。
input要素を使用してコマンドを定義する
input要素で、type属性が送信ボタン、リセットボタン、イメージボタン、ボタン、ラジオボタン、またはチェックボックスのいずれかの状態にある場合、コマンドを定義します。
コマンドのラベルは、次のように決定されます:
もしtype属性が送信ボタン、リセットボタン、イメージボタン、またはボタンの状態にある場合、ラベルは、存在する場合、value属性によって与えられる文字列であり、属性が存在しない場合は、UA依存、ロケール依存の値であり、UAがボタン自体をラベル付けするために使用します。
それ以外の場合、要素がラベル付けされたコントロールである場合、ラベルは、ツリー順で最初のlabel要素の子孫テキストコンテンツです。そのラベル付けされたコントロールが対象の要素である場合。(JavaScript用語では、これはelement.labels[0].textContentによって与えられます。)
それ以外の場合、ラベルは空文字列です。
コマンドのアクセスキーは、その要素の割り当てられたアクセスキーです(存在する場合)。
コマンドのは、その要素に属性がある場合にtrue(非表示)、それ以外の場合はfalseです。
コマンドの無効状態は、その要素またはその祖先の一つがinertである場合、または要素の無効状態が設定されている場合にtrue、それ以外の場合はfalseです。
コマンドのアクションは、要素に対してclickイベントを発火させることです。
option要素を使用してコマンドを定義する
option要素が、祖先にselect要素を持ち、かつvalue属性がないか、value属性が空文字列でない場合、コマンドを定義します。
コマンドのラベルは、その要素のoption要素のlabel属性の値があればその値で、なければoption要素の子孫テキストコンテンツをASCIIホワイトスペースを取り除き、折りたたんだものです。
コマンドのアクセスキーは、その要素の割り当てられたアクセスキー(存在する場合)です。
コマンドのは、その要素に属性がある場合にtrue(非表示)、それ以外の場合はfalseです。
コマンドの無効状態は、その要素が無効である場合、またはその最も近い祖先select要素が無効である場合、またはその要素またはその祖先の一つがinertである場合にtrueとなり、それ以外の場合はfalseです。
もしoption要素の最も近い祖先select要素がmultiple属性を持つ場合、コマンドのアクションは、そのoption要素をトグルすることです。それ以外の場合、アクションは、そのoption要素を選択することです。
legend要素でaccesskey属性を使用してコマンドを定義する
legend要素は、次のすべてが真である場合にコマンドを定義します:
割り当てられたアクセスキーを持つ。
fieldset要素の子である。
その親要素が、コマンドを定義する子孫を持ち、それがlabel要素でもlegend要素でもない場合。この要素が存在する場合、それはlegend要素のaccesskeyデリゲートです。
コマンドのラベルは、その要素の子孫テキストコンテンツです。
コマンドのアクセスキーは、その要素の割り当てられたアクセスキーです。
コマンドの、無効状態、およびアクションファセットは、このlegend要素のaccesskeyデリゲートのそれぞれのファセットと同じです。
この例では、legend要素がaccesskeyを指定しており、これがアクティブになると、input要素にデリゲートされます。
< fieldset >
< legend accesskey = p >
< label > I want < input name = pizza type = number step = 1 value = 1 min = 0 >
pizza(s) with these toppings</ label >
</ legend >
< label >< input name = pizza-cheese type = checkbox checked > Cheese</ label >
< label >< input name = pizza-ham type = checkbox checked > Ham</ label >
< label >< input name = pizza-pineapple type = checkbox > Pineapple</ label >
</ fieldset >
accesskey属性を使用して他の要素でコマンドを定義する
割り当てられたアクセスキーを持つ要素は、コマンドを定義します。
もし以前のセクションで定義された要素が、コマンドを定義すると定義されている場合、そのセクションがこの要素に適用され、このセクションは適用されません。それ以外の場合、このセクションがその要素に適用されます。
コマンドのラベルは要素によって異なります。要素がラベル付きコントロールである場合、最初のlabel要素の子孫テキストコンテンツがラベルになります(JavaScriptの用語では、これはelement.labels[0].textContentで表されます)。それ以外の場合、子孫テキストコンテンツがラベルになります。
コマンドのアクセスキーは、その要素の割り当てられたアクセスキーです。
コマンドのは、要素に属性がある場合にtrue(非表示)、それ以外の場合はfalseです。
コマンドの無効状態は、その要素またはその祖先の一つがinertである場合にtrueとなり、それ以外の場合はfalseです。
コマンドのアクションは、次のステップを実行することです:
dialog要素すべての現行エンジンでサポートされています。
すべての現行エンジンでサポートされています。
open —
ダイアログボックスが表示されているかどうか
[Exposed =Window ]
interface HTMLDialogElement : HTMLElement {
[HTMLConstructor ] constructor ();
[CEReactions ] attribute boolean open ;
attribute DOMString returnValue ;
[CEReactions ] undefined show ();
[CEReactions ] undefined showModal ();
[CEReactions ] undefined close (optional DOMString returnValue );
};
dialog
要素は、小さなウィンドウ(「ダイアログボックス」)の形式で、アプリケーションの一時的な部分を表します。ユーザーは、タスクを実行したり、情報を収集したりするためにこのウィンドウと対話します。ユーザーが作業を完了すると、ダイアログはアプリケーションによって自動的に閉じられるか、ユーザーが手動で閉じることができます。
特にモーダルダイアログは、すべての種類のアプリケーションでおなじみのパターンであるため、著者は、Webアプリケーション内のダイアログが非Webアプリケーションのユーザーにとっても馴染みのある方法で動作するようにする必要があります。
すべてのHTML要素と同様に、dialog
要素を他の種類のコントロールを表現しようとする際に使用することは適合しません。たとえば、コンテキストメニュー、ツールチップ、およびポップアップリストボックスはダイアログボックスではないため、dialog
要素をこれらのパターンを実装するために乱用することは誤りです。
ユーザー向けダイアログの動作で重要な部分は、初期フォーカスの配置です。ダイアログフォーカス手順
は、ダイアログが表示されたときに初期フォーカスに適した候補を選択しようとしますが、特定のダイアログに対するユーザーの期待に一致する正しい選択を慎重に検討する著者に代わるものではないかもしれません。そのため、著者は、ダイアログが開かれた後にユーザーが直ちに対話することを期待されるダイアログの子孫要素にautofocus
属性を使用する必要があります。そのような要素がない場合、著者はdialog 要素自体にautofocus 属性を使用する必要があります。
以下の例では、ダイアログが在庫管理Webアプリケーションで製品の詳細を編集するために使用されています。
< dialog >
< label > Product Number < input type = "text" readonly ></ label >
< label > Product Name < input type = "text" autofocus ></ label >
</ dialog >
もし autofocus
属性が存在しなかった場合、ダイアログフォーカス手順によってプロダクトナンバーフィールドにフォーカスが当てられます。それは合理的な動作ですが、著者はプロダクトナンバーフィールドが読み取り専用であり、ユーザー入力を期待しないため、より関連性の高いフィールドに焦点を当てることを決定しました。そのため、著者は自動フォーカスを使用してデフォルトを上書きしました。
著者がデフォルトでプロダクトナンバーフィールドにフォーカスを合わせたい場合でも、input
要素にautofocusを使用して明示的に指定するのが最善です。これにより、コードの意図が将来の読者に明確になり、将来の更新に対してコードが堅牢であり続けることが保証されます。(たとえば、他の開発者が閉じるボタンを追加し、それをプロダクトナンバーフィールドの前にノードツリー内に配置した場合など)。
ユーザーの行動に関するもう1つの重要な側面は、ダイアログがスクロール可能かどうかです。場合によっては、オーバーフロー(およびそれによるスクロールの発生)は避けられません。たとえば、ユーザーのテキストズーム設定が高い場合などです。しかし、一般的に、ユーザーはスクロール可能なダイアログを期待していません。ダイアログ要素自体がオーバーフローを引き起こす可能性が高いため、ダイアログ要素に大きなテキストノードを直接追加することは特に悪いとされています。著者はそれらを避けるのが最善です。
以下の利用規約ダイアログは、上記の提案に従っています。
< dialog style = "height: 80vh;" >
< div style = "overflow: auto; height: 60vh;" autofocus >
< p > By placing an order via this Web site on the first day of the fourth month of the year
2010 Anno Domini, you agree to grant Us a non-transferable option to claim, for now and for
ever more, your immortal soul.</ p >
< p > Should We wish to exercise this option, you agree to surrender your immortal soul,
and any claim you may have on it, within 5 (five) working days of receiving written
notification from this site or one of its duly authorized minions.</ p >
<!-- ... etc., with many more <p> elements ... -->
</ div >
< form method = "dialog" >
< button type = "submit" value = "agree" > Agree</ button >
< button type = "submit" value = "disagree" > Disagree</ button >
</ form >
</ dialog >
ダイアログフォーカス手順 がデフォルトでスクロール可能な
div
要素を選択したかどうかに注意してください。しかし、前の例と同様に、div に autofocus
を追加して、将来の変更に対しても明確かつ堅牢であるようにしました。
対照的に、利用規約を表現する p 要素にそのようなラッパー
div 要素がない場合、dialog
自体がスクロール可能になり、上記のアドバイスに反することになります。さらに、autofocus
属性がない場合、そのようなマークアップパターンは上記のアドバイスに違反し、デフォルトの動作である ダイアログフォーカス手順 を妨げ、Agree button
にフォーカスがジャンプし、悪いユーザー体験を引き起こす可能性があります。
open 属性は ブール属性 です。指定されると、dialog
要素がアクティブであり、ユーザーがそれと対話できることを示します。
dialog 要素に open
属性が指定されていない場合、ユーザーには表示されません。この要件は、スタイルレイヤーを介して間接的に実装される場合があります。たとえば、提案されたデフォルトのレンダリングをサポートするユーザーエージェントは、この要件を レンダリングセクション に記載されたCSSルールを使用して実装します。
open
属性を削除すると、通常はダイアログが非表示になります。ただし、それを行うと、いくつかの奇妙な追加の結果が発生します:
close イベントは発生しません。
ダイアログが showModal()
メソッドを使用して表示された場合、Document は引き続き モーダルダイアログによってブロックされます。
これらの理由から、open
属性を手動で削除しない方が一般的に良いです。代わりに、close()
メソッドを使用してダイアログを閉じるか、
属性を使用して非表示にしてください。
tabindex 属性は、dialog 要素に指定してはなりません。
dialog.show()
すべての現在のエンジンでサポートされています。
dialog 要素を表示します。
dialog.showModal()
すべての現在のエンジンでサポートされています。
dialog
要素を表示し、最上位のモーダルダイアログとして設定します。
このメソッドは、autofocus
属性を尊重します。
dialog.close([ result ])
すべての現在のエンジンでサポートされています。
dialog 要素を閉じます。
引数が提供されている場合、それは戻り値を提供します。
dialog.returnValue [ = result ]
すべての現在のエンジンでサポートされています。
dialog
の戻り値を返します。
セットすることができ、戻り値を更新します。
show()
メソッドの手順は以下の通りです:
this に
open 属性がある場合、"InvalidStateError" DOMException
をスローします。
this の previously focused element を focused 要素に設定します。
hideUntil を topmost popover ancestor を this、null、および false を指定して実行した結果として設定します。
hideUntil が null の場合、hideUntil を this の node document に設定します。
hideUntil、false、および true を指定して hide all popovers until を実行します。
dialog focusing steps を this に対して実行します。
showModal()
メソッドの手順は以下の通りです:
this
に open 属性がある場合、"InvalidStateError" DOMException
をスローします。
this
が connected でない場合、"InvalidStateError" DOMException
をスローします。
this
が popover showing state
にある場合、"InvalidStateError" DOMException
をスローします。
this の node document を blocked by the modal dialog this として設定します。
これにより、document のフォーカス領域 が inert になります (ただし、現在のフォーカス領域が shadow-including descendant である場合を除きます)。 そのような場合、document のフォーカス領域 はすぐに reset され、ビューポート に戻されます。 数ステップで、より適切な候補を見つけるための処理を行います。
this の node document の top layer が contain しない場合 this を、top layer に要素を追加する 処理を this に対して行います。
this の close watcher を、次のパラメーターで close watcher を確立する の結果として設定します:
cancelAction を
canPreventClose に設定し、イベント を cancel として this で発生させ、その cancelable
属性を canPreventClose に初期化します。
closeAction を dialog を閉じる 処理を this および null で行うように設定します。
this の previously focused element を focused 要素に設定します。
hideUntil を topmost popover ancestor を this、null、および false を指定して実行した結果として設定します。
hideUntil が null の場合、hideUntil を this の node document に設定します。
hideUntil、false、および true を指定して hide all popovers until を実行します。
dialog focusing steps を this に対して実行します。
ダイアログフォーカス手順、ダイアログ 要素
subject が与えられた場合の手順は次の通りです:
control を null に設定します。
subject が autofocus
属性を持っている場合、control を subject に設定します。
control が null の場合、control を subject の フォーカスデリゲート に設定します。
control が null の場合、control を subject に設定します。
control に対して フォーカス手順 を実行します。
control が フォーカス可能
でない場合、これは何もしません。これは subject がフォーカスデリゲートを持たず、ユーザーエージェントが ダイアログ
要素が一般的にフォーカス可能ではないと判断した場合にのみ発生します。その場合、以前の修正 が ドキュメントのフォーカス領域 に適用されます。
control の ノードナビゲーブル の 最上位トラバース可能 の アクティブドキュメント を topDocument とします。
topDocument の オートフォーカス候補 を 空にします。
topDocument の オートフォーカス処理フラグ を true に設定します。
ダイアログ HTML 要素の削除手順
では、removedNode と oldParent が与えられた場合に次の手順が実行されます:
removedNode の クローズウォッチャー が null でない場合:
removedNode の クローズウォッチャー を 破棄します。
removedNode の クローズウォッチャー を null に設定します。
removedNode の ノードドキュメント の トップレイヤー が removedNode を 含んでいる場合、removedNode を 即座にトップレイヤーから削除します。
removedNode の is modal フラグを false に設定します。
close(returnValue) メソッド手順は以下の通りです:
returnValue が指定されていない場合、それを null に設定します。
ダイアログを閉じます this に対して returnValue を設定します。
ダイアログ 要素
subject を 閉じる 必要がある場合、null または文字列 result と共に次の手順を実行します:
subject が open
属性を持っていない場合、終了します。
subject の open 属性を削除します。
subject の is modal フラグが true の場合、トップレイヤーから削除するように要求します。
wasModal を subject の is modal フラグの値に設定します。
subject の is modal フラグを false に設定します。
result が null でない場合、returnValue
属性に result を設定します。
subject の 以前にフォーカスされていた要素 が null でない場合:
element を subject の 以前にフォーカスされていた要素 に設定します。
subject の 以前にフォーカスされていた要素 を null に設定します。
subject の ノードドキュメント の ドキュメントのフォーカス領域 の DOM アンカー が 影響を受ける包括的な子孫 または element のものである場合、wasModal が true の場合は、フォーカス手順 を実行します。この手順を実行する際にビューポートはスクロールされるべきではありません。
要素タスクをキューに追加します、ユーザーインタラクションタスクソース で subject 要素を指定し、イベントを発火させます。
close という名前で、subject
に対して発火します。
subject の クローズウォッチャー が null でない場合:
クローズウォッチャーを破壊します subject の クローズウォッチャー を。
subject の クローズウォッチャー を null に設定します。
returnValue
IDL属性は、取得時に最後に設定された値を返す必要があります。設定時には新しい値に設定する必要があります。要素が作成されたときには、空の文字列に設定される必要があります。
ダイアログ要素に対して、動詞として"show/close"を使用します。これは、より一般的に対義語と考えられる"show/hide"や"open/close"という動詞のペアとは異なるためです。その理由は以下の制約によります:
ダイアログを隠すことは、閉じることとは異なります。ダイアログを閉じると、リターン値が与えられ、イベントが発火し、他のダイアログのためにページのブロックが解除されます。対して、ダイアログを隠すことは純粋に視覚的な属性であり、属性を使用するか、open属性を削除することで既に実行できます。(open属性の削除と、それがどのようにダイアログを隠すかについての
上記の注意点も参照してください。)
ダイアログを表示することは、開くこととは異なります。ダイアログを開くことは、そのダイアログを作成し、表示することからなります(window.open()が新しいウィンドウを作成して表示するのと同様です)。一方、ダイアログを表示することは、既にDOMに存在するダイアログ要素をインタラクティブにし、ユーザーに表示するプロセスです。
上記にもかかわらずdialog.open()メソッドを持たせると、dialog.openプロパティと競合します。
さらに、調査によると、ダイアログ要素のオリジナルデザインにおいて、他の多くのUIフレームワークが"show/close"という動詞のペアを使用していることが明らかになりました。
まとめると、特定の動詞の意味合いと、それが技術コンテキストでどのように使用されるかによって、ダイアログを表示して閉じるといった対のアクションは、必ずしも対義語として表現されるわけではないということです。
各ダイアログ要素には、クローズウォッチャーがあり、これはクローズウォッチャーまたはnullです。初期値はnullです。
各ダイアログ要素にはモーダルフラグがあります。ダイアログ要素が作成されたとき、このフラグはfalseに設定される必要があります。
各HTML要素には、以前にフォーカスされた要素があり、これはnullまたは要素です。初期値はnullです。showModal()およびshow()が呼び出されると、ダイアログフォーカス手順を実行する前に、現在フォーカスされている要素に設定されます。ポップオーバー属性を持つ要素は、ポップオーバー表示アルゴリズムの間にこの要素を現在フォーカスされている要素に設定します。
すべての最新のエンジンでサポートされています。
open
IDL属性は、openコンテンツ属性を反映する必要があります。
このダイアログボックスには小さな注意書きがあります。strong要素を使用して、より重要な部分にユーザーの注意を引きます。
< dialog >
< h1 > ウォレットに追加</ h1 >
< p >< strong >< label for = amt > ウォレットに追加する金貨の枚数は?</ label ></ strong ></ p >
< p >< input id = amt name = amt type = number min = 0 step = 0.01 value = 100 ></ p >
< p >< small > コインを追加するのは自己責任で。</ small ></ p >
< p >< label >< input name = round type = checkbox > 完璧に丸いコインのみ追加する</ label ></ p >
< p >< input type = button onclick = "submit()" value = "コインを追加" ></ p >
</ dialog >
スクリプトは、著者がドキュメントにインタラクティブ性を追加できるようにします。
可能な限り宣言型の代替手段を使用することが推奨されます。宣言型のメカニズムは、多くの場合、保守が容易であり、多くのユーザーがスクリプトを無効にしているためです。
たとえば、詳細を表示するためにセクションを表示または非表示にするスクリプトを使用する代わりに、details要素を使用することができます。
また、スクリプトのサポートがない場合でもアプリケーションが正常に機能するようにすることも推奨されます。
たとえば、著者がテーブルヘッダーにリンクを提供して動的にテーブルを並べ替える場合、そのリンクは、サーバーからソートされたテーブルを要求することで、スクリプトなしでも機能するようにすることができます。
script 要素すべての現在のエンジンでサポートされています。
すべての現在のエンジンでサポートされています。
src属性がない場合は、 type属性の値に依存しますが、スクリプトコンテンツの制限に一致する必要があります。
src 属性がある場合、要素は空であるか、外部スクリプトのインラインドキュメントのみを含む必要があります。
src — リソースのアドレス
type — スクリプトのタイプ
nomodule — モジュールスクリプトをサポートするユーザーエージェントでの実行を防ぐ
async —
フェッチ中にブロックせずに、利用可能になったときにスクリプトを実行
defer — スクリプト実行の遅延
crossorigin
— この要素がクロスオリジンリクエストをどのように処理するか
integrity —
サブリソースインテグリティチェックで使用されるインテグリティメタデータ[SRI]
referrerpolicy
— この要素によって開始されるフェッチに対するリファラーポリシー
blocking — この要素が潜在的にレンダーブロックするかどうか
fetchpriority
— この要素によって開始されたフェッチの優先順位を設定
[Exposed =Window ]
interface HTMLScriptElement : HTMLElement {
[HTMLConstructor ] constructor ();
[CEReactions ] attribute USVString src ;
[CEReactions ] attribute DOMString type ;
[CEReactions ] attribute boolean noModule ;
[CEReactions ] attribute boolean async ;
[CEReactions ] attribute boolean defer ;
[CEReactions ] attribute DOMString ? crossOrigin ;
[CEReactions ] attribute DOMString text ;
[CEReactions ] attribute DOMString integrity ;
[CEReactions ] attribute DOMString referrerPolicy ;
[SameObject , PutForwards =value ] readonly attribute DOMTokenList blocking ;
[CEReactions ] attribute DOMString fetchPriority ;
static boolean supports (DOMString type );
// also has obsolete members
};
script
要素は、著者がドキュメント内に動的なスクリプトやデータブロックを含めることを可能にします。この要素はユーザー向けのコンテンツを表現しません。
すべての現在のエンジンでサポートされています。
type
属性は、スクリプトの種類をカスタマイズすることができます:
属性を省略するか、空の文字列に設定するか、JavaScript MIME タイプ エッセンスマッチに設定すると、スクリプトはクラシックスクリプトとなり、JavaScript のスクリプトトップレベル生成に従って解釈されます。クラシックスクリプトはasync属性およびdefer属性の影響を受けますが、これはsrc属性が設定されている場合に限ります。著者は、冗長な設定を避けるために、type属性を省略することが推奨されます。
属性を "module" としてASCII 大文字小文字を区別しないで設定すると、スクリプトはJavaScript
モジュールスクリプトとなり、JavaScript のモジュールトップレベル生成に従って解釈されます。モジュールスクリプトはdefer属性の影響を受けませんが、async属性の影響を受けます(src属性の状態に関係なく)。
属性を "importmap" としてASCII 大文字小文字を区別しないで設定すると、スクリプトはインポートマップとなり、JSON を含み、モジュール識別子解決の動作を制御するために使用されます。インポートマップはインラインでのみ使用でき、src属性や他のほとんどの属性は意味がなく、それらと共に使用されるべきではありません。
属性を他の任意の値に設定すると、スクリプトはデータブロックとなり、処理されません。script属性(type自体を除く)は、データブロックには何の影響も与えません。著者は、有効な MIME タイプ文字列を使用し、JavaScript MIME タイプエッセンスマッチではないことを示す必要があります。
データブロックは、有効な MIME タイプ文字列を使用して示す必要があり、将来の潜在的な競合を避けるためにこの要件があります。この仕様が将来的にスクリプトの追加タイプを導入する場合、それらは MIME タイプではない値をtype属性に設定することでトリガーされます。現在、module
値がモジュールスクリプトを示しているようにです。今、有効な MIME
タイプ文字列を使用することで、将来のユーザーエージェントでも、データブロックが異なるスクリプトタイプとして再解釈されることはありません。
クラシックスクリプトおよびJavaScript
モジュールスクリプトはインラインで埋め込むことができます。または、指定されている場合、外部スクリプトリソースの URL を指定するsrc属性を使用して外部ファイルからインポートすることができます。srcが指定されている場合、有効な非空の
URL(スペースで囲まれている可能性がある)である必要があります。
インラインのscript要素または外部スクリプトリソースの内容は、クラシックスクリプトおよびJavaScript
モジュールスクリプトそれぞれに対して、JavaScript 仕様のスクリプトまたはモジュール生成の要件に従う必要があります。[JAVASCRIPT]
CSS モジュールスクリプトの外部スクリプトリソースの内容は、CSS 仕様の要件に従う必要があります。[CSS]
JSON モジュールスクリプトの外部スクリプトリソースの内容は、JSON 仕様の要件に従う必要があります。[JSON]
インポートマップのインラインscript要素の内容は、インポートマップ作成要件に従う必要があります。
インポートマップscript要素の場合、src、async、nomodule、defer、crossorigin、integrity、およびreferrerpolicy属性を指定してはなりません。
ドキュメントには、インポートマップscript要素が 1
つ以上含まれていてはなりません。
データブロックを含めるために使用される場合、データはインラインで埋め込まれ、データの形式はtype属性を使用して指定され、script要素の内容は、使用される形式に対して定義された要件に従う必要があります。src、async、nomodule、defer、crossorigin、integrity、referrerpolicy、およびfetchpriority属性は指定してはなりません。
nomodule属性は、ブール属性であり、モジュールスクリプトをサポートするユーザーエージェントでスクリプトが実行されるのを防ぎます。これにより、モダンなユーザーエージェントではモジュールスクリプトを、古いユーザーエージェントではクラシックスクリプトを選択的に実行できるようになります。以下の例を参照してください。nomodule属性は、モジュールスクリプトで指定してはなりません(指定されても無視されます)。
すべての現在のエンジンでサポートされています。
すべての現在のエンジンでサポートされています。
async および defer
属性は、スクリプトの評価方法を示すブール属性です。クラシックスクリプトは、deferまたはasyncを指定できますが、src属性が存在しない限り、これらのどちらも指定してはいけません。モジュールスクリプトはasync属性を指定できますが、defer属性を指定してはいけません。
これらの属性を使用して選択できるモードはいくつかあり、スクリプトの種類に応じて異なります。
クラシックスクリプトの場合、async属性が指定されていると、クラシックスクリプトは解析と並行して並行してフェッチされ、利用可能になり次第評価されます(解析が完了する前に評価される可能性があります)。async属性が指定されておらず、defer属性が指定されている場合、クラシックスクリプトは並行してフェッチされ、ページの解析が完了した時点で評価されます。どちらの属性も指定されていない場合、スクリプトはすぐにフェッチおよび評価され、これらの処理が完了するまで解析がブロックされます。
モジュールスクリプトの場合、async属性が指定されている場合、モジュールスクリプトとそのすべての依存関係は解析と並行してフェッチされ、モジュールスクリプトは利用可能になり次第評価されます(解析が完了する前に評価される可能性があります)。それ以外の場合、モジュールスクリプトとその依存関係は解析と並行してフェッチされ、ページの解析が完了した時点で評価されます(defer属性はモジュールスクリプトには影響しません)。
これらは以下の模式図にまとめられています:
これらの属性の正確な処理の詳細は、主に歴史的な理由により、HTML
のさまざまな側面を含む、やや複雑なものとなっています。そのため、実装要件は必然的に仕様全体に散在しています。以下のアルゴリズム(このセクション)は、この処理の核心を説明していますが、これらのアルゴリズムは HTML
のscript 開始および終了タグの解析ルール、外部コンテンツ内およびXML 内のルール、document.write()メソッドの処理、スクリプティングの処理などに関連しています。
document.write()メソッドを使用して挿入された場合、script要素は通常実行されます(通常、他のスクリプトの実行や HTML 解析をブロックします)。innerHTMLおよびouterHTML属性を使用して挿入された場合、まったく実行されません。
defer属性は、async属性が指定されている場合でも指定できます。これにより、deferのみをサポートし、asyncをサポートしないレガシー Web
ブラウザが、デフォルトのブロッキング動作ではなく、defer動作にフォールバックするようにします。
crossorigin属性は、CORS 設定属性です。クラシックスクリプトの場合、他のオリジンから取得されたスクリプトのエラー情報が公開されるかどうかを制御します。モジュールスクリプトの場合、クロスオリジンリクエストに使用されるクレデンシャルモードを制御します。
クラシックスクリプトとは異なり、モジュールスクリプトには、クロスオリジンフェッチにCORS プロトコルの使用が必要です。
integrity属性は、この要素が担当するリクエストのインテグリティメタデータを表します。値はテキストです。integrity属性は、src属性が指定されていない場合、指定してはいけません。[SRI]
referrerpolicy属性は、リファラーポリシー属性です。これは、スクリプトのフェッチ時およびそれからインポートされるすべてのスクリプトに使用されるリファラーポリシーを設定するためのものです。[REFERRERPOLICY]
インポートされたスクリプトをフェッチする際に使用される、script要素のreferrerポリシーの例ですが、他のサブリソースには適用されません:
< script referrerpolicy = "origin" >
fetch( '/api/data' ); // <script>のreferrerポリシーでフェッチされていません
import ( './utils.mjs' ); // <script>のreferrerポリシー("origin"の場合)でフェッチされます
</ script >
blocking属性は、ブロッキング属性です。
fetchpriority属性は、フェッチ優先度属性です。これは、スクリプトをフェッチする際に使用される優先度を設定するためのものです。
src、type、nomodule、async、defer、crossorigin、integrity、referrerpolicy、およびfetchpriorityの属性を動的に変更しても直接的な影響はありません。これらの属性は、以下に記載された特定のタイミングでのみ使用されます。
IDL属性src、type、defer、integrity、およびblockingは、それぞれ同じ名前のコンテンツ属性を反映する必要があります。
HTMLScriptElement/referrerPolicy
すべての現在のエンジンでサポートされています。
HTMLScriptElement インターフェイスの referrerPolicy IDL属性は、referrerpolicy
コンテンツ属性を反映する必要があり、既知の値のみに限定されます。
HTMLScriptElement インターフェイスの fetchPriority IDL属性は、fetchpriority
コンテンツ属性を反映する必要があり、既知の値のみに限定されます。
HTMLScriptElement インターフェイスの crossOrigin IDL属性は、crossorigin
コンテンツ属性を反映する必要があり、既知の値のみに限定されます。
HTMLScriptElement インターフェイスの noModule IDL属性は、nomodule コンテンツ属性を反映する必要があります。
HTMLScriptElement インターフェイスの async のゲッターステップは以下の通りです:
async のセッターステップは以下の通りです:
script.text [ = value ]
要素の子テキストコンテンツを返します。
設定可能で、指定された値で要素の子要素を置き換えます。
HTMLScriptElement.supports(type)
指定されたtypeがユーザーエージェントによってサポートされているスクリプトタイプである場合は true を返します。この仕様書での可能なスクリプトタイプは
"classic"、"module"、および"importmap"ですが、将来的に他のものが追加される可能性もあります。
text
属性のゲッターは、このscript要素の
子テキストコンテンツを返さなければなりません。
text属性の
セッターは、指定された値でこのscript要素の
内部のすべてのテキストを置き換えなければなりません。
HTMLScriptElement/supports_static
すべての現在のエンジンでサポートされています。
supports(type)メソッドのステップは以下の通りです:
もしtypeが"classic" であるなら、trueを返します。
もしtypeが"module" であるなら、trueを返します。
もしtypeが"importmap" であるなら、trueを返します。
falseを返します。
type引数はこれらの値に完全に一致する必要があります。ASCII
大文字と小文字を区別しない一致は行いません。これはtypeコンテンツ属性の値が処理される方法や、
DOMTokenListの
supports()
メソッドの動作とは異なりますが、WorkerType
列挙型がWorker()コンストラクターで使用される方法と一致します。
この例では、2つのscript要素が使用されています。1つは外部のクラシックスクリプトを埋め込み、もう1つはデータブロックとしていくつかのデータを含みます。
< script src = "game-engine.js" ></ script >
< script type = "text/x-game-map" >
........ U......... e
o............ A.... e
..... A..... AAA.... e
. A.. AAA... AAAAA... e
</ script >
この場合、データはスクリプトによってビデオゲームのマップを生成するために使用される可能性があります。ただし、データはそのように使用される必要はありません。マップデータがページの他の部分に埋め込まれており、ここでのデータブロックは、サイトの検索エンジンがゲームマップ内の特定の機能を探しているユーザーを支援するために使用されるだけかもしれません。
次の例は、script要素を使用して、ドキュメントの他の部分で使用される関数を定義する方法を示しています。これはクラシックスクリプトの一部として使用されます。また、この例では、ドキュメントが解析されている間にスクリプトを呼び出して、フォームの出力を初期化する方法も示しています。
< script >
function calculate( form) {
var price = 52000 ;
if ( form. elements. brakes. checked)
price += 1000 ;
if ( form. elements. radio. checked)
price += 2500 ;
if ( form. elements. turbo. checked)
price += 5000 ;
if ( form. elements. sticker. checked)
price += 250 ;
form. elements. result. value = price;
}
</ script >
< form name = "pricecalc" onsubmit = "return false" onchange = "calculate(this)" >
< fieldset >
< legend > 車の価格を計算する</ legend >
< p > 基本費用: £52000.</ p >
< p > 追加オプションを選択:</ p >
< ul >
< li >< label >< input type = checkbox name = brakes > セラミックブレーキ (£1000)</ label ></ li >
< li >< label >< input type = checkbox name = radio > 衛星ラジオ (£2500)</ label ></ li >
< li >< label >< input type = checkbox name = turbo > ターボチャージャー (£5000)</ label ></ li >
< li >< label >< input type = checkbox name = sticker > "XZ" ステッカー (£250)</ label ></ li >
</ ul >
< p > 合計: £< output name = result ></ output ></ p >
</ fieldset >
< script >
calculate( document. forms. pricecalc);
</ script >
</ form >
次のサンプルは、script要素を使用して、外部のJavaScriptモジュールスクリプトを含める方法を示しています。
< script type = "module" src = "app.mjs" ></ script >
このモジュールおよびその依存関係(ソースファイル内のJavaScriptimport文を通じて表現されるもの)はすべてフェッチされます。結果として得られるモジュールグラフがすべてインポートされ、ドキュメントの解析が終了すると、app.mjsの内容が評価されます。
さらに、同じWindow内の他のscript要素からのコードがapp.mjsからモジュールをインポートする場合(例:import "./app.mjs";を介して)、以前に作成された同じJavaScriptモジュールスクリプトがインポートされます。
この例は、モダンなユーザーエージェント向けにJavaScriptモジュールスクリプトを、古いユーザーエージェント向けにクラシックスクリプトを含める方法を示しています。
< script type = "module" src = "app.mjs" ></ script >
< script nomodule defer src = "classic-app-bundle.js" ></ script >
JavaScriptモジュールスクリプトをサポートするモダンなユーザーエージェントでは、script要素にnomodule属性が付いている場合、その要素は無視され、script要素にtypeが"module"と指定されている場合、そのスクリプトがフェッチされて評価されます(JavaScriptモジュールスクリプトとして)。逆に、古いユーザーエージェントは"module"というscript要素を無視します。これは彼らにとって未知のスクリプトタイプだからです。しかし、他のscript要素を(クラシックスクリプトとして)フェッチして評価することには問題がありません。なぜなら、それらはnomodule属性を実装していないからです。
次のサンプルは、script要素を使用して、ドキュメントのテキストにいくつかの置換を行い、より興味深い読書体験を提供するためのインラインJavaScriptモジュールスクリプトを書く方法を示しています(例:ニュースサイトでの使用):[XKCD1288]
< script type = "module" >
import { walkAllTextNodeDescendants } from "./dom-utils.mjs" ;
const substitutions = new Map([
[ "witnesses" , "these dudes I know" ]
[ "allegedly" , "kinda probably" ]
[ "new study" , "Tumblr post" ]
[ "rebuild" , "avenge" ]
[ "space" , "spaaace" ]
[ "Google glass" , "Virtual Boy" ]
[ "smartphone" , "Pokédex" ]
[ "electric" , "atomic" ]
[ "Senator" , "Elf-Lord" ]
[ "car" , "cat" ]
[ "election" , "eating contest" ]
[ "Congressional leaders" , "river spirits" ]
[ "homeland security" , "Homestar Runner" ]
[ "could not be reached for comment" , "is guilty and everyone knows it" ]
]);
function substitute( textNode) {
for ( const [ before, after] of substitutions. entries()) {
textNode. data = textNode. data. replace( new RegExp( `\\b ${ before} \\b` , "ig" ), after);
}
}
walkAllTextNodeDescendants( document. body, substitute);
</ script >
JavaScriptモジュールスクリプトを使用することで得られる主な機能には、他のJavaScriptモジュールから関数をインポートする機能、デフォルトで厳密モードが有効になること、そしてトップレベルの宣言がグローバルオブジェクトに新しいプロパティを導入しないことが含まれます。また、このscript要素がドキュメント内のどこに現れても、ドキュメントの解析が完了し、依存関係(dom-utils.mjs)がフェッチされ評価されるまで評価されないことに注意してください。
次のサンプルは、JSONモジュールスクリプトがJavaScriptモジュールスクリプト内からどのようにインポートされるかを示しています:
< script type = "module" >
import peopleInSpace from "http://api.open-notify.org/astros.json" with { type: "json" };
const list = document. querySelector( "#people-in-space" );
for ( const { craft, name } of peopleInSpace. people) {
const li = document. createElement( "li" );
li. textContent = ` ${ name} / ${ craft} ` ;
list. append( li);
}
</ script >
モジュールスクリプトのMIMEタイプのチェックは厳格です。JSONモジュールスクリプトのフェッチが成功するためには、HTTPレスポンスがJSON
MIMEタイプを持っている必要があります。例えばContent-Type: text/jsonです。逆に、ステートメントのwith { type: "json" }部分が省略された場合、意図がJavaScriptモジュールスクリプトをインポートすることであるとみなされ、HTTPレスポンスがJavaScript MIMEタイプでない場合、フェッチは失敗します。
script要素には、いくつかの関連する状態があります。
script要素には、パーサードキュメントがあり、これはnullまたはDocumentであり、最初はnullです。これはHTMLパーサーとXMLパーサーによってscript要素に設定され、これらの要素の処理に影響を与えます。nullでないパーサードキュメントを持つscript要素はパーサー挿入済みとして知られています。
script要素には、準備時ドキュメントがあり、これはnullまたはDocumentであり、最初はnullです。これは、準備の間にドキュメント間を移動するスクリプトが実行されないようにするために使用されます。
script要素には、最初はtrueである非同期強制というブール値があります。これはHTMLパーサーとXMLパーサーによって、彼らが挿入するscript要素に設定され、要素にasync属性が追加されるとfalseになります。
script要素には、外部ファイルからのブール値があり、最初はfalseです。これは、その時点での要素のsrc属性に基づいて、スクリプトが準備されたときに決定されます。
script要素には、最初はfalseであるパーサー実行の準備ができているブール値があります。これは、パーサー挿入済みの要素のみが使用し、パーサーがスクリプトを実行するタイミングを知らせるために使用されます。
script要素には、最初はfalseであるすでに開始されたブール値があります。
script要素には、最初はfalseであるロードイベントを遅延させるブール値があります。
script要素には、null、"classic"、"module"、または"importmap"のいずれかであるタイプがあり、最初はnullです。これは、その時点での要素のtype属性に基づいて、要素が準備されたときに決定されます。
script要素には、"uninitialized"、null(エラーを表す)、スクリプト、またはインポートマップ解析結果のいずれかである結果があり、最初は"uninitialized"です。
script要素には、一連の手順またはnullである結果が準備できたときに実行する手順があり、最初はnullです。スクリプト、インポートマップ解析結果、またはnullのresultを指定して、script要素elを準備完了としてマークするには:
elの結果をresultに設定します。
もしelの結果が準備できたときに実行する手順がnullでない場合、それらを実行します。
elの結果が準備できたときに実行する手順をnullに設定します。
elのロードイベントの遅延をfalseに設定します。
script要素elがasync属性またはdefer属性を持たずに、タイプが"classic"であり、elがパーサー挿入済みの場合、elは暗黙的に潜在的なレンダーブロックになります。
script要素elをコピーcopyに複製する際の複製手順は、copyのすでに開始されたを、elのすでに開始されたに設定することです。
async属性がscript要素elに追加された場合、ユーザーエージェントはelの非同期強制をfalseに設定しなければなりません。
script要素elのロードイベントを遅延させるがtrueである場合、ユーザーエージェントはelの準備時ドキュメントのロードイベントを遅延させる必要があります。
次のリストに記載されているイベントのいずれかが発生した場合、script要素elがパーサー挿入済みでない場合、ユーザーエージェントはelをスクリプト要素を準備する必要があります:
script要素が接続されます。
script要素が接続され、ノードまたはドキュメントフラグメントが、その時点で挿入された任意のscript要素の後に、そのscript要素に挿入されます。
script要素が接続されており、以前はその要素にそのような属性がなかった場所にsrc属性が設定されています。
script要素elを準備するには:
もし、el の すでに開始されている が真であれば、処理を終了します。
el の パーサー文書 を parser document とします。
el の パーサー文書 を null に設定します。
これは、パーサー挿入された スクリプト
要素が、空であるか、サポートされていないスクリプト言語を指定しているために実行に失敗した場合、他のスクリプトが後でそれらを変更して再実行させることができるようにするためです。
もし parser document が null でなく、el が async
属性を持っていない場合、el の 強制非同期 を真に設定します。
これは、パーサー挿入された スクリプト
要素が実行に失敗したが、その後スクリプトによって動的に更新されて実行される場合に、async
属性が設定されていなくても、非同期で実行されるようにするためです。
el の 子テキスト内容 を source text とします。
もし el が src
属性を持っておらず、source text が空文字列であれば、処理を終了します。
もし el が 接続されていない 場合、処理を終了します。
以下のいずれかが真である場合:
el が空の値を持つ type
属性を持っている場合
この場合、この スクリプト 要素の
スクリプトブロックのタイプ文字列 を "text/javascript" に設定します。
それ以外の場合、el が type
属性を持っている場合、その属性の値から先頭および末尾のASCIIホワイトスペースを削除したものを
スクリプトブロックのタイプ文字列 に設定します。
それ以外の場合、el が空でない language
属性を持っている場合、その属性の値と "text/" を連結したものを スクリプトブロックのタイプ文字列 に設定します。
もし スクリプトブロックのタイプ文字列 が JavaScript MIMEタイプの本質的な一致 であれば、el
の type を
"classic" に設定します。
それ以外の場合、スクリプトブロックのタイプ文字列 が文字列 "module" と ASCII大文字小文字を区別しない 一致である場合、el の type を
"module" に設定します。
それ以外の場合、スクリプトブロックのタイプ文字列 が文字列 "importmap" と ASCII大文字小文字を区別しない 一致である場合、el の type を
"importmap" に設定します。
それ以外の場合、処理を終了します。(スクリプトは実行されず、el の type は null のままです。)
もし parser document が null でない場合、el の パーサー文書 を parser document に戻し、el の 強制非同期 を false に設定します。
el の すでに開始されている を true に設定します。
もし parser document が null でなく、かつ parser document が el の 準備時間文書 と等しくない場合、処理を終了します。
もし el に対して スクリプトが無効化 されている場合、処理を終了します。
スクリプトが無効化
されている場合の定義には、次のスクリプトが含まれます: XMLHttpRequest
の responseXML
文書内のスクリプト、DOMParser
によって作成された文書内のスクリプト、XSLTProcessor の transformToDocument
機能によって作成された文書内のスクリプト、およびスクリプトが最初に挿入された文書内のスクリプト Document が createDocument()
APIを使用して作成されたものである場合など。
もし el が nomodule
コンテンツ属性を持ち、かつその type が
"classic" である場合、処理を終了します。
これは、モジュールスクリプト に nomodule
を指定しても効果がないことを意味します。アルゴリズムは引き続き処理を続行します。
もし el が src
コンテンツ属性を持っておらず、要素のインライン動作がコンテンツセキュリティポリシーによってブロックされるべきか?
アルゴリズムが el、"script" および source text に対して "Blocked"
を返した場合、処理を終了します。[CSP]
もし el が event 属性および for 属性を持ち、かつ
el の type が
"classic" である場合、以下を行います:
for を el の for
属性の値とします。
event を el の event
属性の値とします。
event と for の 先頭および末尾のASCIIホワイトスペースを削除 します。
for が文字列 "window" と ASCII大文字小文字を区別しない 一致でない場合、処理を終了します。
event が文字列 "onload" または "onload()" と ASCII大文字小文字を区別しない 一致でない場合、処理を終了します。
もし el が charset
属性を持っている場合、その属性の値から エンコーディングを取得 した結果を encoding とします。
もし el が charset
属性を持っていないか、または エンコーディングの取得 に失敗した場合、encoding を el の ノード文書 の エンコーディング に設定します。
もし el の type が "module"
である場合、このエンコーディングは無視されます。
classic script CORS setting を、el の crossorigin
コンテンツ属性の現在の状態に設定します。
module script credentials mode を、el の crossorigin
コンテンツ属性の CORS 設定属性のクレデンシャルモード に設定します。
cryptographic nonce を el の [[CryptographicNonce]] 内部スロットの値に設定します。
もし el が integrity
属性を持っている場合、その属性の値を integrity metadata に設定します。
それ以外の場合、integrity metadata を空の文字列に設定します。
referrer policy を、el の referrerpolicy
コンテンツ属性の現在の状態に設定します。
fetch priority を、el の fetchpriority
コンテンツ属性の現在の状態に設定します。
もし el が パーサー挿入された
ものであれば、parser metadata を "parser-inserted" に設定し、それ以外の場合は
"not-parser-inserted" に設定します。
options を スクリプトフェッチオプション とし、その 暗号論的ナンス を cryptographic nonce、integrity metadata を integrity metadata、parser metadata を parser metadata、クレデンシャルモード を module script credentials mode、リファラーポリシー を referrer policy、フェッチ優先度 を fetch priority に設定します。
settings object を el の ノード文書 の 関連設定オブジェクト に設定します。
もし el が src
コンテンツ属性を持っている場合、以下の処理を行います:
もし el の type が "importmap" であれば、要素タスクをキューに追加 し、el に対して イベントを発火
させ、処理を終了します。
外部インポートマップスクリプトは現在サポートされていません。サポートを追加するための議論については、WICG/import-maps issue #235 を参照してください。
src を el の src
属性の値に設定します。
もし src が空の文字列であれば、要素タスクをキューに追加 し、el に対して イベントを発火 させ、処理を終了します。
el の 外部ファイルから を true に設定します。
url を、src を相対パスとして el の ノード文書 に対して URLをエンコードして解析する の結果に設定します。
もし url が失敗した場合、要素タスクをキューに追加 し、el に対して イベントを発火 させ、処理を終了します。
もし el が レンダリングブロックの可能性がある ものであれば、レンダリングをブロック します。
el の ロードイベントを遅延させる を true に設定します。
もし el が現在 レンダリングブロック中 であれば、options の レンダリングブロック を true に設定します。
以下の手順を与えられた result に対する onComplete として設定します:
el の type に基づいてスイッチします:
classic"
url、settings object、options、classic script CORS setting、encoding、および onComplete を与えて クラシックスクリプトをフェッチ します。
module"
もし el が integrity
属性を持っていない場合、url と settings object を使用して モジュールのインテグリティメタデータを解決する
の結果を options の インテグリティメタデータ
に設定します。
url、settings object、options、および onComplete を与えて 外部モジュールスクリプトグラフをフェッチ します。
パフォーマンス上の理由から、ユーザーエージェントは、el が接続される(その間に crossorigin
属性が変更されないと予想される)と期待して、src
属性が設定されるとすぐにクラシックスクリプトまたはモジュールグラフをフェッチを開始することがあります。いずれの場合も、el が 接続される
と、ロードがこのステップで説明されるように開始される必要があります。UAがそのようなプリフェッチを行うが、el が接続されないか、src
属性が動的に変更されるか、crossorigin
属性が動的に変更されると、そのスクリプトは実行されず、フェッチプロセスは事実上無駄になります。
もし el が src
コンテンツ属性を持っていない場合:
el の type に基づいてスイッチします:
classic"
クラシックスクリプトを作成 の結果を使用して script を source text、settings object、base URL、および options と共に設定します。
準備完了としてマーク script を与えて el を設定します。
module"
el の ロードイベントを遅延させる を true に設定します。
もし el が レンダリングブロックの可能性がある ものであれば:
レンダリングをブロック します。
options の レンダリングブロック を true に設定します。
source text、base URL、settings object、および options を与えて インラインモジュールスクリプトグラフをフェッチ し、result を指定して次の手順を実行します:
要素タスクをキューに追加 し、el に次のステップを実行させます:
準備完了としてマーク el を与えて result を設定します。
ここでタスクをキューに追加することは、インラインモジュールスクリプトに依存関係がないか、構文エラーが同期的に発生した場合でも、スクリプト要素を実行 するプロセスが同期的に行われないことを意味します。
importmap"
もし el の 関連するグローバルオブジェクト の インポートマップが許可されている が偽であれば、要素タスクをキューに追加 し、el に対して イベントを発火 させ、処理を終了します。
el の 関連するグローバルオブジェクト の インポートマップが許可されている を偽に設定します。
result を、source text および base URL を与えて インポートマップ解析結果を作成する の結果に設定します。
準備完了としてマーク result を与えて el を設定します。
もし el の type が "classic" であり、かつ
el が src 属性を持っている場合、または
el の type
が "module" である場合:
もし el が async
属性を持っている場合、または el の 強制非同期 が真である場合:
scripts を、el の 準備時間文書 の できるだけ早く実行されるスクリプトのセット に設定します。
追加 el を scripts に追加します。
el の 結果が準備完了したときに実行する手順 を以下に設定します:
スクリプト要素を実行 します el を。
削除 el を scripts から。
それ以外の場合、el が パーサー挿入された ものでない場合:
scripts を、el の 準備時間文書 の できるだけ早く順番に実行されるスクリプトのリスト に設定します。
追加 el を scripts に。
el の 結果が準備完了したときに実行する手順 を以下に設定します:
もし scripts[0] が el でなければ、これらの手順を中止します。
次の条件を満たしている限り、scripts が空でなく、かつ scripts[0] の 結果 が
"uninitialized" でない場合:
スクリプト要素を実行 します scripts[0] を。
削除 scripts[0] を。
それ以外の場合、el が defer
属性を持っている場合、または el の type が "module" である場合:
追加 el をその パーサー文書 の 文書の解析が終了したときに実行されるスクリプトのリスト に。
el の 結果が準備完了したときに実行する手順 を以下に設定します: el の パーサー実行準備完了 を真に設定します。(パーサーがスクリプトの実行を処理します。)
それ以外の場合:
el の パーサー文書 の 解析ブロック中のスクリプトを保留 に設定します el を。
レンダリングをブロック します el で。
el の 結果が準備完了したときに実行する手順 を以下に設定します: el の パーサー実行準備完了 を真に設定します。(パーサーがスクリプトの実行を処理します。)
それ以外の場合:
次のすべての条件が真である場合:
classic" である。
この場合、以下を実行します:
el の パーサー文書 の 解析ブロック中のスクリプトを保留 に設定します。
el の パーサー実行準備完了 を真に設定します。(パーサーがスクリプトの実行を処理します。)
それ以外の場合、即座に スクリプト要素を実行 el を、他のスクリプトがすでに実行されている場合でも。
各 文書 には 解析をブロックしているスクリプトを保留中 があります。これは スクリプト 要素または null
であり、初期値は null です。
各 文書 には 可能な限り早く実行されるスクリプトのセット があります。これは セット の
スクリプト
要素であり、初期値は空です。
各 文書 には 可能な限り早く順番に実行されるスクリプトのリスト があります。これは
リスト の スクリプト 要素であり、初期値は空です。
各 文書 には 文書の解析が終了したときに実行されるスクリプトのリスト
があります。これは リスト の スクリプト 要素であり、初期値は空です。
もし、パーサーをブロックする スクリプト
要素が通常はそのパーサーのブロックを解除する前に他の 文書
に移動された場合でも、そのスクリプトがパーサーをブロックする条件がもはや適用されなくなるまで、そのパーサーを引き続きブロックします(例: そのスクリプトが 解析をブロックしているスクリプトを保留中 であるため、元の 文書 に スクリプトをブロックしているスタイルシートが存在
していたが、スクリプトがそのブロック中のスタイルシートが読み込まれる前に他の 文書
に移動された場合でも、そのスクリプトはスタイルシートがすべて読み込まれるまでパーサーをブロックし続け、その後スクリプトが実行され、パーサーがブロック解除されます)。
与えられた スクリプト 要素
el を 実行する ための手順は次のとおりです:
el の ノード文書 を document とします。
el の 準備時間文書 が document と等しくない場合、処理を終了します。
レンダリングのブロックを解除 します el で。
もし el が 外部ファイルから のものであるか、el の type が
"module" である場合、document の 破壊的な書き込みを無視するカウンター を増やします。
el の type に基づいてスイッチします:
classic"
document の currentScript
オブジェクトに最近設定された値を oldCurrentScript とします。
もし el の root が
シャドウルート でなければ、document の currentScript
属性を el に設定します。それ以外の場合は、null に設定します。
これは 文書ツリー内 のチェックを使用しません。これは el
が実行前に文書から削除される可能性があり、そのシナリオでは currentScript
が依然としてそれを指す必要があるためです。
クラシックスクリプトを実行 します el の 結果 に基づいて。
document の currentScript
属性を oldCurrentScript に設定します。
module"
断言: document の currentScript
属性が null であることを確認します。
モジュールスクリプトを実行 します el の 結果 に基づいて。
importmap"
インポートマップを登録 します el の 関連するグローバルオブジェクト および el の 結果 に基づいて。
前のステップで増やされた場合は、document の 破壊的な書き込みを無視するカウンター を減らします。
ユーザーエージェントは JavaScript をサポートする必要はありません。JavaScript
以外の言語が登場し、ウェブブラウザによって同様に広く採用された場合、この標準を更新する必要があります。そのような時が来るまで、script
要素の処理モデルに基づいて、他の言語を実装することはこの標準と矛盾します。
サーバーは、JavaScript リソースに対して text/javascript
を使用するべきです。Updates to ECMAScript Media Types に従って、他の JavaScript MIME タイプ を使用すべきではなく、非 JavaScript MIME タイプ を使用してはなりません。[RFC9239]
外部の JavaScript リソースに対して、`Content-Type`
ヘッダー内の MIME タイプパラメータは一般的に無視されます。(一部のケースでは、`charset` パラメータが影響を与える場合があります。)ただし、script 要素の type 属性に対しては重要であり、JavaScript MIME タイプのエッセンス一致の概念を使用します。
例えば、type 属性が
"text/javascript; charset=utf-8" に設定されたスクリプトは、パース時に有効な JavaScript MIME タイプ であっても評価されません。
さらに、再度外部の JavaScript リソースに対して、スクリプト要素を準備する アルゴリズムおよび Fetch
に詳細に記載されているように、`Content-Type`
ヘッダー処理に関して特別な考慮が必要です。[FETCH]
このセクションで説明されているかなり奇妙な制限を回避する最も簡単で安全な方法は、スクリプト内のリテラルにこれらのシーケンスが現れる場合に、"<!--" を
"\x3C!--"、"<script" を "\x3Cscript"、および "</script" を
"\x3C/script"
としてエスケープし、そうした構文を式に使用するコードを書かないようにすることです。こうすることで、このセクションで制限されている問題、つまり、歴史的な理由により、HTMLでの script
ブロックの解析が、これらのシーケンスに対して直感的でない動作をするという問題を完全に回避できます。
script
要素の 子孫テキスト内容 は、以下の ABNF の script
生成規則に一致する必要があります。その文字セットは Unicode です。[ABNF]
script = outer * ( comment-open inner comment-close outer )
outer = < any string that doesn 't contain a substring that matches not-in-outer >
not-in-outer = comment-open
inner = < any string that doesn 't contain a substring that matches not-in-inner >
not-in-inner = comment-close / script-open
comment-open = "<!--"
comment-close = "-->"
script-open = "<" s c r i p t tag-end
s = %x0053 ; U+0053 ラテン大文字 S
s =/ %x0073 ; U+0073 ラテン小文字 s
c = %x0043 ; U+0043 ラテン大文字 C
c =/ %x0063 ; U+0063 ラテン小文字 c
r = %x0052 ; U+0052 ラテン大文字 R
r =/ %x0072 ; U+0072 ラテン小文字 r
i = %x0049 ; U+0049 ラテン大文字 I
i =/ %x0069 ; U+0069 ラテン小文字 i
p = %x0050 ; U+0050 ラテン大文字 P
p =/ %x0070 ; U+0070 ラテン小文字 p
t = %x0054 ; U+0054 ラテン大文字 T
t =/ %x0074 ; U+0074 ラテン小文字 t
tag-end = %x0009 ; U+0009 キャラクタタブ (タブ)
tag-end =/ %x000A ; U+000A ラインフィード (LF)
tag-end =/ %x000C ; U+000C フォームフィード (FF)
tag-end =/ %x0020 ; U+0020 スペース
tag-end =/ %x002F ; U+002F ソリダス (/)
tag-end =/ %x003E ; U+003E 大なり記号 (>)
script
要素が スクリプトのドキュメント
を含む場合、以下のセクションで説明するように、その要素の内容にさらに制限があります。
次のスクリプトはこの問題を示しています。たとえば、次のような文字列を含むスクリプトがあるとします:
const example = 'この文字列を考えてください: <!-- <script>' ;
console. log( example);
この文字列を script
ブロック内に直接配置すると、上記の制限に違反します:
< script >
const example = 'この文字列を考えてください: <!-- <script>' ;
console. log( example);
</ script >
しかし、より大きな問題は、これらの制限に違反する理由です。実際にはスクリプトが奇妙に解析されるということです。上記のスクリプトブロックは終了していません。つまり、このスニペットで
"</script>" エンドタグのように見えるものは、実際にはまだ script
ブロックの一部です。スクリプトは実行されません(終了していないため)。もし実行されるとすれば、マークアップが次のように見える場合、スクリプト(ここで強調表示されています)が有効な JavaScript
ではないため、失敗します:
< script >
const example = 'この文字列を考えてください: <!-- <script>' ;
console. log( example);
</ script >
<!-- 見かけによらず、これはまだスクリプトの一部です! -->
< script >
... // これはまだ同じスクリプトブロックです...
</ script >
ここで何が起こっているかというと、レガシーな理由から、HTML内の script
要素内の "<!--" と "<script" 文字列はバランスが取れていないと、パーサーがブロックを閉じることを考慮しないためです。
このセクションの冒頭で述べたように問題のある文字列をエスケープすることで、この問題を完全に回避できます:
< script >
// 注意: `\x3C` は `<` のエスケープシーケンスです。
const example = 'この文字列を考えてください: \x3C!-- \x3Cscript>' ;
console. log( example);
</ script >
<!-- これはスクリプトブロック間の単なるコメントです -->
< script >
... // これは新しいスクリプトブロックです
</ script >
これらのシーケンスがスクリプト式に自然に現れることがあります。次の例のように:
if ( x<!-- y) { ... }
if ( player< script ) { ... }
そのような場合、文字はエスケープできませんが、式を書き直してシーケンスが発生しないようにすることができます。次のように:
if ( x < !-- y) { ... }
if ( !-- y > x) { ... }
if ( ! ( -- y) > x) { ... }
if ( player < script) { ... }
if ( script > player) { ... }
これにより、別の落とし穴も回避できます。関連する歴史的な理由で、クラシックスクリプト内の文字列 "<!--" は実際には行コメントの開始として扱われます。まるで "//" のように。
script
要素の src
属性が指定されている場合、その script
要素の内容がある場合、その内容から派生した text IDL
属性の値が、以下の ABNF に示す documentation 生成規則と一致する必要があります。文字セットは Unicode です。[ABNF]
documentation = * ( * ( space / tab / comment ) [ line-comment ] newline )
comment = slash star * ( not-star / star not-slash ) 1* star slash
line-comment = slash slash * not-newline
; characters
tab = %x0009 ; U+0009 キャラクタタブ (タブ)
newline = %x000A ; U+000A ラインフィード (LF)
space = %x0020 ; U+0020 スペース
star = %x002A ; U+002A アスタリスク (*)
slash = %x002F ; U+002F スラッシュ (/)
not-newline = %x0000-0009 / %x000B-10FFFF
; U+000A ラインフィード (LF) 以外の スカラ値
not-star = %x0000-0029 / %x002B-10FFFF
; U+002A アスタリスク (*) 以外の スカラ値
not-slash = %x0000-002E / %x0030-10FFFF
; U+002F スラッシュ (/) 以外の スカラ値
これは、要素の内容を JavaScript コメントとして配置することに相当します。
この要件は、script
要素の内容に関する前述の構文制限に加えて適用されます。
これにより、著者はライセンス情報や API
情報などのドキュメントを、外部スクリプトファイルを参照しながらドキュメント内に含めることができます。構文は制約されていますが、著者が誤って有効なスクリプトのように見える内容を含めることを防ぎます。その場合でも
src
属性が提供されます。
< script src = "cool-effects.js" >
// create new instances using:
// var e = new Effect();
// start the effect using .play, stop using .stop:
// e.play();
// e.stop();
</ script >
script 要素と XSLT の相互作用このセクションは規範的ではありません。
この仕様書では、script 要素と XSLT
の相互作用について定義していません。しかし、これを実際に定義する他の仕様書がない場合、既存の実装に基づいて実装者向けにいくつかのガイドラインを示します。
<?xml-stylesheet?> 処理命令によって XSLT 変換プログラムがトリガーされ、ブラウザが直接 DOM 変換を実装する場合、XSLT プロセッサによって作成された
script 要素は、parser document
が正しく設定され、ドキュメント順に実行される必要があります(defer または async
がマークされているスクリプトを除く)、変換が行われている間に 即座に 実行されます。
XSLTProcessor の transformToDocument()
メソッドは、ブラウジングコンテキスト が null の Document オブジェクトに要素を追加します。それに応じて、これらが作成する
script 要素は、prepare the script
element アルゴリズムで already started を
true に設定し、決して実行されないようにする必要があります(スクリプトが無効)。それでも、その async IDL 属性が、async コンテンツ属性がない場合には
false を返すように、parser document
を設定する必要があります。
XSLTProcessor の transformToFragment()
メソッドは、document.createElementNS()
を使用して要素を作成することで手動で構築されたものと同等のフラグメントを作成する必要があります。たとえば、parser document が null の script 要素を作成し、already started を false
に設定し、フラグメントがドキュメントに挿入されたときに実行されるようにする必要があります。
最初の 2 つのケースと最後のケースの主な違いは、最初の 2 つが Document
を操作するのに対し、最後のケースはフラグメントを操作する点です。
noscript
要素全ての現行エンジンでサポートされています。
head要素内の
HTML文書で、先祖にnoscript要素が存在しない場合。
noscript要素が存在しない場合。
head要素内において、
任意の順序で、0個以上のlink要素、0個以上のstyle要素、
および0個以上のmeta要素を含む。
head要素外の場合:
透過的であるが、子孫にnoscript要素を含んではならない。
HTMLElementを使用。
noscript要素は、スクリプトが有効な場合は何も表さず、スクリプトが無効な場合はその子要素を表します。
これは、スクリプトをサポートするユーザーエージェントとサポートしないユーザーエージェントに異なるマークアップを提供するために使用され、ドキュメントの解析方法に影響を与えます。
HTML文書で使用する場合、許可されるコンテンツモデルは次のとおりです:
head要素内で、スクリプトが無効な場合
head要素内で、スクリプトが有効な場合
noscript要素にはテキストのみを含める必要があります。ただし、noscript要素をコンテキスト要素として、テキストコンテンツを入力として、HTMLフラグメント解析アルゴリズムを実行することによって、link、style、およびmeta要素のみを含むノードリストが生成される必要があります。また、解析エラーが発生しないようにする必要があります。
head要素外で、スクリプトが無効な場合
noscript要素のコンテンツモデルは、透過的です。ただし、noscript要素には、先祖要素としてnoscript要素を含めることはできません(つまり、noscriptはネストできません)。
head要素外で、スクリプトが有効な場合
noscript要素にはテキストのみを含める必要があります。ただし、そのテキストは、次のアルゴリズムを実行して、noscript要素およびscript要素がない準拠したドキュメントが得られるようにする必要があります。また、そのアルゴリズムの実行中に例外が発生せず、HTMLパーサーが解析エラーを警告しないようにする必要があります:
これらの複雑な手順は、歴史的な理由から、noscript要素が、HTMLパーサーによって、スクリプトが有効か無効かに基づいて異なる方法で処理されるために必要です。
noscript
要素は、XML文書で使用してはなりません。
noscript
要素は、HTML構文でのみ有効であり、XML構文では効果がありません。
これは、スクリプトが有効な場合にパーサーを「オフ」にすることで、要素の内容が純粋なテキストとして扱われ、実際の要素として扱われないようにするためです。XMLにはこれを行うためのメカニズムが定義されていません。
noscript
要素には他の要件はありません。特に、noscript
要素の子要素は、スクリプトが有効な場合でも、フォーム送信、
スクリプト、およびその他の処理から免除されません。
次の例では、noscript
要素がスクリプトのフォールバックとして使用されています。
< form action = "calcSquare.php" >
< p >
< label for = x > Number</ label > :
< input id = "x" name = "x" type = "number" >
</ p >
< script >
var x = document. getElementById( 'x' );
var output = document. createElement( 'p' );
output. textContent = 'Type a number; it will be squared right then!' ;
x. form. appendChild( output);
x. form. onsubmit = function () { return false ; }
x. oninput = function () {
var v = x. valueAsNumber;
output. textContent = v + ' squared is ' + v * v;
};
</ script >
< noscript >
< input type = submit value = "Calculate Square" >
</ noscript >
</ form >
スクリプトが無効な場合、サーバー側で計算を実行するボタンが表示されます。スクリプトが有効な場合、値はリアルタイムで計算されます。
noscript
要素は強力な手段ですが、スクリプトが有効であっても、ページのスクリプトが何らかの理由で失敗する可能性があります。
このため、noscriptの使用は避け、
代わりにスクリプトを設計して、スクリプトがないページからスクリプトがあるページに動的に変更する方法を採用する方が一般的に望ましいです。以下の例のように:
< form action = "calcSquare.php" >
< p >
< label for = x > Number</ label > :
< input id = "x" name = "x" type = "number" >
</ p >
< input id = "submit" type = submit value = "Calculate Square" >
< script >
var x = document. getElementById( 'x' );
var output = document. createElement( 'p' );
output. textContent = 'Type a number; it will be squared right then!' ;
x. form. appendChild( output);
x. form. onsubmit = function () { return false ; }
x. oninput = function () {
var v = x. valueAsNumber;
output. textContent = v + ' squared is ' + v * v;
};
var submit = document. getElementById( 'submit' );
submit. parentNode. removeChild( submit);
</ script >
</ form >
template要素全ての現在のエンジンでサポートされています。
全ての現在のエンジンでサポートされています。
colgroup要素の子として、span属性を持たないもの。shadowrootmode
— ストリーミング宣言的シャドウルートを可能にします。shadowrootdelegatesfocus
— 宣言的シャドウルートにフォーカスを委任します。shadowrootclonable
— 宣言的シャドウルートをクローン可能にします。shadowrootserializable
— 宣言的シャドウルートをシリアライズ可能にします。[Exposed =Window ]
interface HTMLTemplateElement : HTMLElement {
[HTMLConstructor ] constructor ();
readonly attribute DocumentFragment content ;
[CEReactions ] attribute DOMString shadowRootMode ;
[CEReactions ] attribute boolean shadowRootDelegatesFocus ;
[CEReactions ] attribute boolean shadowRootClonable ;
[CEReactions ] attribute boolean shadowRootSerializable ;
};
template要素は、スクリプトによってドキュメントにクローンして挿入できるHTMLフラグメントを宣言するために使用されます。
レンダリングにおいて、template要素は何も表しません。
shadowrootmode内容属性は、列挙型属性であり、次のキーワードと状態があります:
| キーワード | 状態 | 簡単な説明 |
|---|---|---|
open |
open | template要素は、開かれた宣言的シャドウルートを表します。 |
closed |
closed | template要素は、閉じた宣言的シャドウルートを表します。 |
shadowrootmode属性の無効な値のデフォルトおよび欠損値のデフォルトは、いずれもnone状態です。
shadowrootdelegatesfocus内容属性はブール属性です。
shadowrootclonable内容属性はブール属性です。
shadowrootserializable内容属性はブール属性です。
template要素のテンプレート内容は要素自体の子ではありません。
DOM操作の結果として、template要素がテキストノードや要素ノードを含むことも可能です。しかし、それを含むことはtemplate要素の内容モデルの違反となります。なぜなら、その内容モデルは何もないとして定義されているためです。
例えば、次のドキュメントを考えてみましょう:
<!doctype html>
< html lang = "en" >
< head >
< title > Homework</ title >
< body >
< template id = "template" >< p > Smile!</ p ></ template >
< script >
let num = 3 ;
const fragment = document. getElementById( 'template' ). content. cloneNode( true );
while ( num-- > 1 ) {
fragment. firstChild. before( fragment. firstChild. cloneNode( true ));
fragment. firstChild. textContent += fragment. lastChild. textContent;
}
document. body. appendChild( fragment);
</ script >
</ html >
p要素は、template内にありますが、DOMではtemplateの子ではなく、DocumentFragmentの子として返されます。
スクリプトがappendChild()をtemplate要素で呼び出した場合、それは他の要素と同様にtemplate要素に子を追加しますが、これはtemplate要素の内容モデルの違反です。
template.content
全ての現在のエンジンでサポートされています。
テンプレート内容(DocumentFragment)を返します。
各template要素には、それに関連付けられたDocumentFragmentオブジェクトがあり、それがテンプレート内容となります。テンプレート内容には準拠要件はありません。template要素が作成されると、ユーザーエージェントはテンプレート内容を確立するために次の手順を実行しなければなりません:
docをtemplate要素のノードドキュメントの適切なテンプレート内容の所有ドキュメントとします。
docをDocumentFragmentオブジェクトとして作成し、そのノードドキュメントをdocとし、ホストをtemplate要素とします。
作成したばかりのDocumentFragmentオブジェクトを、template要素のテンプレート内容に設定します。
Documentdocの適切なテンプレート内容の所有ドキュメントは、次のアルゴリズムによって返されるDocumentです:
docがこのアルゴリズムによって作成されたDocumentでない場合:
docにまだ関連する無効なテンプレートドキュメントがない場合:
new docを新しいDocumentとして作成し(ブラウジングコンテキストはnull)、このステップにおける「このアルゴリズムによって作成されたDocument」とします。
docがHTMLドキュメントである場合、new docをHTMLドキュメントとしてもマークします。
docの関連する無効なテンプレートドキュメントをnew docに設定します。
docをdocの関連する無効なテンプレートドキュメントに設定します。
このアルゴリズムによって作成されていない各Documentには、すべてのtemplate要素のテンプレート内容を所有するための単一のDocumentが与えられ、その内容がブラウジングコンテキスト内にないようにし、無効なままにします(例:スクリプトが実行されないようにする)。一方で、このアルゴリズムによって作成されたDocument内のtemplate要素は、同じDocument所有者をその内容に再利用します。
docを返します。
採用ステップ(nodeとoldDocumentをパラメータとして)template要素の場合は次のとおりです:
docをnodeのノードドキュメントの適切なテンプレート内容の所有ドキュメントとします。
採用するnodeのテンプレート内容(DocumentFragmentオブジェクト)をdocに追加します。
contentゲッターステップは、テンプレート内容がShadowRootノードでない場合にtemplateのテンプレート内容を返します。それ以外の場合はnullを返します。
shadowRootModeIDL属性は、shadowrootmode内容属性を反映し、既知の値のみに制限されます。
shadowRootDelegatesFocusIDL属性は、shadowrootdelegatesfocus内容属性を反映しなければなりません。
shadowRootClonableIDL属性は、shadowrootclonable内容属性を反映しなければなりません。
shadowRootSerializableIDL属性は、shadowrootserializable内容属性を反映しなければなりません。
複製ステップは、template要素nodeをコピーcopyに複製する際に、次の手順を実行します:
呼び出し元の複製アルゴリズムで複製子フラグが設定されていない場合は、終了します。
コピーされた内容を、nodeのテンプレート内容のすべての子を複製した結果として、documentをcopyのテンプレート内容のノードドキュメントに設定し、複製子フラグを設定した状態で取得します。
コピーされた内容をcopyのテンプレート内容に追加します。
この例では、スクリプトがデータ構造からのデータを使用して表を4列に埋めています。この際、マークアップから構造を手動で生成する代わりに、templateを使用して要素構造を提供しています。
<!DOCTYPE html>
< html lang = 'en' >
< title > Cat data</ title >
< script >
// データはここでハードコードされていますが、サーバーから提供されることもあります
var data = [
{ name: 'Pillar' , color: 'Ticked Tabby' , sex: 'Female (neutered)' , legs: 3 },
{ name: 'Hedral' , color: 'Tuxedo' , sex: 'Male (neutered)' , legs: 4 },
];
</ script >
< table >
< thead >
< tr >
< th > Name < th > Color < th > Sex < th > Legs
</ tbody >
< template id = "row" >
< tr >< td >< td >< td >< td >
</ template >
</ table >
< script >
var template = document. querySelector( '#row' );
for ( var i = 0 ; i < data. length; i += 1 ) {
var cat = data[ i];
var clone = template. content. cloneNode( true );
var cells = clone. querySelectorAll( 'td' );
cells[ 0 ]. textContent = cat. name;
cells[ 1 ]. textContent = cat. color;
cells[ 2 ]. textContent = cat. sex;
cells[ 3 ]. textContent = cat. legs;
template. parentNode. appendChild( clone);
} </ script >
この例では、cloneNode()を使用してtemplateの内容を複製していますが、同じことを行うdocument.importNode()を使用することもできます。この2つのAPIの違いは、ノードドキュメントが更新されるタイミングだけです。cloneNode()では、ノードがappendChild()によって追加されるときに更新され、document.importNode()では、ノードが複製されるときに更新されます。
template要素とXSLTおよびXPathの相互作用このセクションは規範的ではありません。
この仕様書は、XSLTおよびXPathがtemplate要素とどのように相互作用するかを定義していません。ただし、これを実際に定義する他の仕様書がない場合には、以下に実装者向けのガイドラインを示します。これらは、この仕様書で説明されている他の処理と整合性を持つことを意図しています:
この仕様書で説明されているように動作するXMLパーサーに基づくXSLTプロセッサは、template要素がその子孫としてテンプレート内容を含むかのように動作する必要があります。
DOMを出力するXSLTプロセッサは、template要素に入るノードが、要素のテンプレート内容に配置されるようにする必要があります。
この仕様書で説明されているHTMLパーサーまたはXMLパーサーを使用して解析されたDocumentに適用されるXPath DOM
APIを使用したXPath評価は、テンプレート内容を無視する必要があります。
slot要素全ての現行エンジンでサポートされています。
全ての現行エンジンでサポートされています。
name — シャドウツリーのスロットの名前
[Exposed =Window ]
interface HTMLSlotElement : HTMLElement {
[HTMLConstructor ] constructor ();
[CEReactions ] attribute DOMString name ;
sequence <Node > assignedNodes (optional AssignedNodesOptions options = {});
sequence <Element > assignedElements (optional AssignedNodesOptions options = {});
undefined assign ((Element or Text )... nodes );
};
dictionary AssignedNodesOptions {
boolean flatten = false ;
};
slot要素はスロットを定義します。これは通常、シャドウツリーで使用されます。slot要素は、割り当てられたノードが存在する場合はそれらを表し、そうでない場合はその内容を表します。
name内容属性には任意の文字列値を含めることができます。これは、スロットの名前を表します。
name属性は他の要素にスロットを割り当てるために使用されます。slot要素がname属性を持つ場合、その値と一致するslot属性を持つ要素がそのスロットに割り当てられます。このslot要素がシャドウツリーの子であり、そのツリーのルートのホストが対応するslot属性値を持つ場合に限ります。
slot.name
全ての現行エンジンでサポートされています。
slot.assignedNodes()
全ての現行エンジンでサポートされています。
slot.assignedNodes({ flatten: true })
slot要素についても同様に処理します。それを再帰的に繰り返し、slot要素がなくなるまで続けます。
slot.assignedElements()
HTMLSlotElement/assignedElements
全ての現行エンジンでサポートされています。
slot.assignedElements({ flatten: true })
assignedNodes({ flatten: true })と同じものを返しますが、要素に限定されます。
slot.assign(...nodes)
nameIDL属性は同名の内容属性を反映する必要があります。
slot要素には手動で割り当てられたノードがあり、これはassign()によって設定された順序付けされたセットのスロッタブルです。このセットは最初は空です。
手動で割り当てられたノードセットは、弱参照を使ってスロッタブルを実装することができます。なぜなら、このセットはスクリプトから直接アクセスできないからです。
assignedNodes(options)メソッドの手順は以下の通りです:
もしoptions["flatten"]がfalseであれば、thisの割り当てられたノードを返します。
フラット化されたスロッタブルを見つける結果を返します。このときthisを使用します。
assignedElements(options)メソッドの手順は以下の通りです:
もしoptions["flatten"]がfalseであれば、thisの割り当てられたノードを、Elementノードのみにフィルタリングして返します。
フラット化されたスロッタブルを見つける結果を、Elementノードのみにフィルタリングして返します。このときthisを使用します。
全ての現行エンジンでサポートされています。
assign(...nodes)メソッドの手順は以下の通りです:
各nodeについて、thisの手動で割り当てられたノードを、nodeの手動スロット割り当てをnullに設定します。
nodesSetを新しい順序付けされたセットに設定します。
各nodeについて:
もしnodeの手動スロット割り当てがslotに関連している場合、そのslotからnodeを削除します。
nodeの手動スロット割り当てをthisに設定します。
nodeをnodesSetに追加します。
thisの手動で割り当てられたノードをnodesSetに設定します。
ツリーのスロッタブル割り当てを、thisのルートに対して実行します。
canvas 要素
すべての現行エンジンでサポートされています。
すべての現行エンジンでサポートされています。
a要素、img要素(usemap属性を持つもの)、button要素、input要素(type属性がチェックボックス状態またはラジオボタン状態にあるもの)、input要素(ボタンであるもの)、およびselect要素(multiple属性または表示サイズが1を超えるもの)。
width — 水平方向の寸法
height — 垂直方向の寸法
typedef (CanvasRenderingContext2D or ImageBitmapRenderingContext or WebGLRenderingContext or WebGL2RenderingContext or GPUCanvasContext ) RenderingContext ;
[Exposed =Window ]
interface HTMLCanvasElement : HTMLElement {
[HTMLConstructor ] constructor ();
[CEReactions ] attribute unsigned long width ;
[CEReactions ] attribute unsigned long height ;
RenderingContext ? getContext (DOMString contextId , optional any options = null );
USVString toDataURL (optional DOMString type = "image/png", optional any quality );
undefined toBlob (BlobCallback _callback , optional DOMString type = "image/png", optional any quality );
OffscreenCanvas transferControlToOffscreen ();
};
callback BlobCallback = undefined (Blob ? blob );
canvas
要素は、解像度依存のビットマップキャンバスをスクリプトで提供し、グラフ、ゲームグラフィック、アート、その他のビジュアルイメージを動的に描画するために使用できます。
著者は、canvas
要素を、より適切な要素が利用可能な場合には使用しないようにすべきです。たとえば、ページの見出しを描画するために canvas
要素を使用するのは不適切です。見出しの希望する表示がグラフィカルに強調されたものである場合でも、それは通常 h1
のような適切な要素を使用してマークアップし、CSS や シャドウツリー のような補助技術を使用してスタイル設定を行うべきです。
著者が canvas
要素を使用する場合、canvas
のビットマップと本質的に同じ機能または目的をユーザーに伝えるコンテンツも提供しなければなりません。このコンテンツは、canvas
要素の内容として配置されることがあります。canvas 要素の内容がある場合、それは要素のフォールバックコンテンツです。
インタラクティブな視覚メディアにおいて、canvas 要素で スクリプトが有効 であり、かつ canvas
要素のサポートが有効になっている場合、canvas
要素は、要素のビットマップである動的に作成された画像で構成される 埋め込みコンテンツ を 表します。
インタラクティブでない静的な視覚メディアにおいて、canvas
要素が以前にレンダリングコンテキストと関連付けられている場合(例:
ページがインタラクティブな視覚メディアで表示され、その後印刷された場合、またはページレイアウトプロセス中に実行されたスクリプトが要素上に描画した場合)、canvas
要素は、要素の現在のビットマップとサイズを持つ 埋め込みコンテンツ を 表します。それ以外の場合、要素はその フォールバックコンテンツ を表します。
非視覚メディアおよび、視覚メディアで canvas 要素の スクリプトが無効 である場合、または canvas
要素のサポートが無効になっている場合、canvas 要素は代わりにその フォールバックコンテンツ を 表します。
canvas 要素が 埋め込みコンテンツ を表している場合でも、ユーザーは canvas 要素の子孫(フォールバックコンテンツ 内)にフォーカスを当てることができます。要素が フォーカスされる
と、キーボードインタラクションイベントのターゲットとなります(ただし、要素自体は表示されていない場合でも)。これにより、著者はインタラクティブなキャンバスをキーボードでアクセス可能にすることができます。著者はインタラクティブな領域と
フォーカス可能な領域 を フォールバックコンテンツ
に一対一に対応させる必要があります。(フォーカスはマウスインタラクションイベントには影響しません。)[UIEVENTS]
最も近い canvas 要素の祖先が レンダリングされて いて、埋め込みコンテンツ を 表して いる場合、その要素は 関連するキャンバスフォールバックコンテンツとして使用されている 要素です。
canvas
要素には、要素のビットマップのサイズを制御するための 2 つの属性、width と height があります。これらの属性が指定されている場合、値は 有効な非負整数 でなければなりません。非負整数を解析するためのルール を使用して、その数値を 取得 します。属性が存在しない場合、またはその値の解析にエラーが発生した場合は、代わりにデフォルト値が使用されなければなりません。width 属性のデフォルト値は 300
であり、height 属性のデフォルト値は
150 です。
width または height 属性の値を設定する際、canvas 要素の コンテキストモード が プレースホルダー
に設定されている場合、ユーザーエージェントは "InvalidStateError" DOMException
をスローし、属性の値を変更せずにそのままにしておかなければなりません。
canvas 要素が 埋め込みコンテンツ を表しているときの 自然な寸法 は、要素のビットマップの寸法と等しくなります。
ユーザーエージェントは、canvas
とそのレンダリングコンテキストのビットマップに対して、1 座標空間単位あたり 1 ピクセルの画像データで構成される正方形のピクセル密度を使用しなければなりません。
canvas
要素は、スタイルシートによって任意にサイズ変更が可能ですが、そのビットマップは 'object-fit' CSS
プロパティの影響を受けます。
canvas 要素のビットマップ、ImageBitmap オブジェクトのビットマップ、および CanvasRenderingContext2D
や ImageBitmapRenderingContext
などのレンダリングコンテキストに関連する一部のビットマップには、真または偽に設定できる origin-clean
フラグがあります。canvas 要素または
ImageBitmap オブジェクトが作成されると、そのビットマップの origin-clean フラグは最初は
true に設定されなければなりません。
canvas
要素には、レンダリングコンテキストがバインドされることがあります。最初は、レンダリングコンテキストはバインドされていません。レンダリングコンテキストがバインドされているかどうか、およびどの種類のレンダリングコンテキストであるかを追跡するために、canvas には、キャンバスコンテキストモード もあります。これにより、最初は なし
に設定されますが、この仕様で定義されたアルゴリズムによって プレースホルダー、2d、ビットマップレンダラー、webgl、webgl2、または webgpu に変更できます。
そのキャンバスコンテキストモードがなしのとき、canvas要素にはレンダリングコンテキストがなく、そのビットマップは透明な黒であり、自然な幅は要素の幅属性の数値に等しく、自然な高さは要素の高さ属性の数値に等しく、これらの値はCSSピクセルで解釈され、属性が設定、変更、または削除されるたびに更新されます。
canvas 要素の キャンバスコンテキストモード が
プレースホルダー
の場合、その要素にはレンダリングコンテキストがありません。これは OffscreenCanvas
オブジェクトのプレースホルダーとして機能し、OffscreenCanvas
オブジェクトのレンダリングコンテキストによって canvas 要素の内容が更新されます。
canvas 要素が 埋め込みコンテンツ を表している場合、それは
塗装ソース を提供します。その幅は要素の 自然な幅 に等しく、高さは要素の
自然な高さ に等しく、その外観は要素のビットマップです。
width と height
の内容属性が設定、削除、変更された場合、またはすでに持っている値に冗長に設定された場合、ユーザーエージェントは canvas 要素の コンテキストモード
に対応する以下の表の行からアクションを実行しなければなりません。
|
Action | |
|---|---|
|
WebGL の仕様に定義されている動作に従います。[WEBGL] | |
|
WebGPU に定義されている動作に従います。[WEBGPU] | |
|
コンテキストの ビットマップモード が ブランク
に設定されている場合、 | |
|
何もしない。 | |
|
何もしない。 |
Support in all current engines.
Support in all current engines.
width と height IDL
属性は、それぞれの同名のコンテンツ属性を 反映 しなければならず、同じデフォルトを持ちます。
context = canvas.getContext(contextId [, options ])
Support in all current engines.
キャンバス上で描画するための API を公開するオブジェクトを返します。contextId は、希望する API を指定します。次のいずれかの値を指定します: "2d"、"bitmaprenderer"、"webgl"、"webgl2"、または
"webgpu"。options
は、その API によって処理されます。
この仕様では、"2d" と
"bitmaprenderer"
コンテキストが定義されています。WebGL の仕様では、"webgl" および
"webgl2"
コンテキストが定義されています。WebGPU は "webgpu"
コンテキストを定義しています。[WEBGL] [WEBGPU]
サポートされていない contextId が指定された場合や、キャンバスが別のコンテキストタイプで既に初期化されている場合 (例えば、"2d"
コンテキストを取得しようとした後で、"webgl"
コンテキストを取得しようとする場合) には、null を返します。
getContext(contextId, options) メソッドを canvas
要素で呼び出すと、次のステップが実行されます:
options が オブジェクト でない場合、options を null に設定します。
options を JavaScript 値に変換 した結果に設定します。
次の表の列ヘッダーがこの canvas 要素の キャンバスコンテキストモード に一致し、行ヘッダーが
contextId に一致するセルの手順を実行します。
| none | 2d | bitmaprenderer | webgl または webgl2 | webgpu | placeholder | |
|---|---|---|---|---|---|---|
"2d"
|
|
このメソッドが同じ最初の引数で最後に呼び出されたときに返されたのと同じオブジェクトを返します。 |
null を返します。 |
null を返します。 |
null を返します。 |
" |
"bitmaprenderer"
|
|
null を返します。 |
このメソッドが同じ最初の引数で最後に呼び出されたときに返されたのと同じオブジェクトを返します。 |
null を返します。 |
null を返します。 |
" |
"webgl" または "webgl2"、ユーザーエージェントが現在の構成で WebGL
機能をサポートしている場合
|
null を返します。 |
null を返します。 |
このメソッドが同じ最初の引数で最後に呼び出されたときに返されたのと同じオブジェクトを返します。 |
null を返します。 |
" | |
"webgpu"、ユーザーエージェントが現在の構成で WebGPU
機能をサポートしている場合
|
|
null を返します。 |
null を返します。 |
null を返します。 |
このメソッドが同じ最初の引数で最後に呼び出されたときに返されたのと同じオブジェクトを返します。 |
" |
| サポートされていない値* |
null を返します。 |
null を返します。 |
null を返します。 |
null を返します。 |
null を返します。 |
" |
* 例えば、ユーザーエージェントがグラフィックハードウェアの能力を使い果たし、ソフトウェアのフォールバック実装がない場合の "webgl" または
"webgl2"
値など。
url = canvas.toDataURL([ type [, quality ] ])
すべての現行エンジンでサポートされています。
キャンバス内の画像の data: URL を返します。
最初の引数が指定されている場合、返される画像の形式 (例: PNG や JPEG) を制御します。デフォルトは "image/png"
です。指定された形式がサポートされていない場合も、この形式が使用されます。第二引数は、品質が可変な画像形式 (例: "image/jpeg") の場合に適用され、0.0 から 1.0
までの範囲で結果の画像の品質レベルを示す数値です。
"image/png"
以外の形式を使用しようとする場合、返された文字列が "data:image/png," または "data:image/png;"
のいずれかで始まるかどうかを確認することで、画像が本当に要求された形式で返されたかを確認できます。これが当てはまる場合、画像は PNG
であり、要求された形式はサポートされていないことになります。(唯一の例外は、キャンバスの高さまたは幅がゼロの場合、結果が単に "data:," となることがあります。)
canvas.toBlob(callback [, type [, quality ] ])
すべての現行エンジンでサポートされています。
キャンバス内の画像を含むファイルを表す Blob
オブジェクトを作成し、そのオブジェクトへのハンドルを持つコールバックを呼び出します。
第二引数が指定されている場合、返される画像の形式 (例: PNG や JPEG) を制御します。デフォルトは "image/png"
です。指定された形式がサポートされていない場合も、この形式が使用されます。第三引数は、品質が可変な画像形式 (例: "image/jpeg") の場合に適用され、0.0 から 1.0
までの範囲で結果の画像の品質レベルを示す数値です。
canvas.transferControlToOffscreen()
HTMLCanvasElement/transferControlToOffscreen
すべての現行エンジンでサポートされています。
新しく作成された OffscreenCanvas
オブジェクトを返します。このオブジェクトは、canvas
要素をプレースホルダーとして使用します。いったん canvas 要素が
OffscreenCanvas オブジェクトのプレースホルダーになると、その自然サイズは変更できなくなり、レンダリングコンテキストを持つことはできません。プレースホルダーキャンバスの内容は、OffscreenCanvas の 関連エージェント の イベントループ の レンダリングの更新 ステップで更新されます。
toDataURL(type, quality)
メソッドは、呼び出されたとき、以下の手順を実行する必要があります:
この canvas
要素のビットマップの origin-clean フラグが false に設定されている場合、"SecurityError" DOMException
をスローします。
この canvas
要素のビットマップにピクセルがない場合 (すなわち、水平寸法または垂直寸法がゼロの場合)、文字列 "data:," を返します。(これは、最も短い data: URL であり、text/plain
リソース内の空の文字列を表します。)
file を、この canvas
要素のビットマップのファイルとしてのシリアル化 によって取得し、type および quality が指定されていれば、それらを渡します。
file が null の場合、"data:," を返します。
toBlob(callback, type, quality)
メソッドは、呼び出されたとき、以下の手順を実行する必要があります:
この canvas
要素のビットマップの origin-clean フラグが false に設定されている場合、"SecurityError" DOMException
をスローします。
result を null に設定します。
この canvas
要素のビットマップにピクセルがある場合 (すなわち、水平寸法も垂直寸法もゼロでない場合)、result にこの canvas
要素のビットマップのコピーを設定します。
以下の手順を並行して実行します:
result が null でない場合、result を ファイルとしてのシリアル化 し、type および quality が指定されていれば、それらを使用します。
要素タスクをキューに入れ、キャンバスブロブシリアル化タスクソース に対して、canvas
要素を与え、以下の手順を実行します:
result が null でない場合、result をこの canvas
要素の 関連レルム 内で作成された新しい Blob
オブジェクトに設定し、result を表します。[FILEAPI]
コールバック関数を呼び出し、« result
» と "report" を渡します。
transferControlToOffscreen() メソッドは、呼び出されたとき、以下の手順を実行する必要があります:
この canvas 要素の コンテキストモード
が none に設定されていない場合、"InvalidStateError" DOMException
をスローします。
offscreenCanvas を新しい OffscreenCanvas
オブジェクトに設定し、その幅と高さはこの canvas 要素の width および height
コンテンツ属性の値に等しくします。
offscreenCanvas の プレースホルダー canvas 要素 を、この canvas
要素への弱参照に設定します。
offscreenCanvas を返します。
すべての現行エンジンでサポートされています。
すべての現行エンジンでサポートされています。
すべての現行エンジンでサポートされています。
すべての現行エンジンでサポートされています。
すべての現行エンジンでサポートされています。
typedef (HTMLImageElement or
SVGImageElement ) HTMLOrSVGImageElement ;
typedef (HTMLOrSVGImageElement or
HTMLVideoElement or
HTMLCanvasElement or
ImageBitmap or
OffscreenCanvas or
VideoFrame ) CanvasImageSource ;
enum PredefinedColorSpace { " srgb " , " display-p3 " };
enum CanvasFillRule { " nonzero " , " evenodd " };
dictionary CanvasRenderingContext2DSettings {
boolean alpha = true ;
boolean desynchronized = false ;
PredefinedColorSpace colorSpace = "srgb";
boolean willReadFrequently = false ;
};
enum ImageSmoothingQuality { " low " , " medium " , " high " };
[Exposed =Window ]
interface CanvasRenderingContext2D {
// back-reference to the canvas
readonly attribute HTMLCanvasElement canvas ;
CanvasRenderingContext2DSettings getContextAttributes ();
};
CanvasRenderingContext2D includes CanvasState ;
CanvasRenderingContext2D includes CanvasTransform ;
CanvasRenderingContext2D includes CanvasCompositing ;
CanvasRenderingContext2D includes CanvasImageSmoothing ;
CanvasRenderingContext2D includes CanvasFillStrokeStyles ;
CanvasRenderingContext2D includes CanvasShadowStyles ;
CanvasRenderingContext2D includes CanvasFilters ;
CanvasRenderingContext2D includes CanvasRect ;
CanvasRenderingContext2D includes CanvasDrawPath ;
CanvasRenderingContext2D includes CanvasUserInterface ;
CanvasRenderingContext2D includes CanvasText ;
CanvasRenderingContext2D includes CanvasDrawImage ;
CanvasRenderingContext2D includes CanvasImageData ;
CanvasRenderingContext2D includes CanvasPathDrawingStyles ;
CanvasRenderingContext2D includes CanvasTextDrawingStyles ;
CanvasRenderingContext2D includes CanvasPath ;
interface mixin CanvasState {
// state
undefined save (); // push state on state stack
undefined restore (); // pop state stack and restore state
undefined reset (); // reset the rendering context to its default state
boolean isContextLost (); // return whether context is lost
};
interface mixin CanvasTransform {
// transformations (default transform is the identity matrix)
undefined scale (unrestricted double x , unrestricted double y );
undefined rotate (unrestricted double angle );
undefined translate (unrestricted double x , unrestricted double y );
undefined transform (unrestricted double a , unrestricted double b , unrestricted double c , unrestricted double d , unrestricted double e , unrestricted double f );
[NewObject ] DOMMatrix getTransform ();
undefined setTransform (unrestricted double a , unrestricted double b , unrestricted double c , unrestricted double d , unrestricted double e , unrestricted double f );
undefined setTransform (optional DOMMatrix2DInit transform = {});
undefined resetTransform ();
};
interface mixin CanvasCompositing {
// compositing
attribute unrestricted double globalAlpha ; // (default 1.0)
attribute DOMString globalCompositeOperation ; // (default "source-over")
};
interface mixin CanvasImageSmoothing {
// image smoothing
attribute boolean imageSmoothingEnabled ; // (default true)
attribute ImageSmoothingQuality imageSmoothingQuality ; // (default low)
};
interface mixin CanvasFillStrokeStyles {
// colors and styles (see also the CanvasPathDrawingStyles and CanvasTextDrawingStyles interfaces)
attribute (DOMString or CanvasGradient or CanvasPattern ) strokeStyle ; // (default black)
attribute (DOMString or CanvasGradient or CanvasPattern ) fillStyle ; // (default black)
CanvasGradient createLinearGradient (double x0 , double y0 , double x1 , double y1 );
CanvasGradient createRadialGradient (double x0 , double y0 , double r0 , double x1 , double y1 , double r1 );
CanvasGradient createConicGradient (double startAngle , double x , double y );
CanvasPattern ? createPattern (CanvasImageSource image , [LegacyNullToEmptyString ] DOMString repetition );
};
interface mixin CanvasShadowStyles {
// shadows
attribute unrestricted double shadowOffsetX ; // (default 0)
attribute unrestricted double shadowOffsetY ; // (default 0)
attribute unrestricted double shadowBlur ; // (default 0)
attribute DOMString shadowColor ; // (default transparent black)
};
interface mixin CanvasFilters {
// filters
attribute DOMString filter ; // (default "none")
};
interface mixin CanvasRect {
// rects
undefined clearRect (unrestricted double x , unrestricted double y , unrestricted double w , unrestricted double h );
undefined fillRect (unrestricted double x , unrestricted double y , unrestricted double w , unrestricted double h );
undefined strokeRect (unrestricted double x , unrestricted double y , unrestricted double w , unrestricted double h );
};
interface mixin CanvasDrawPath {
// path API (see also CanvasPath)
undefined beginPath ();
undefined fill (optional CanvasFillRule fillRule = "nonzero");
undefined fill (Path2D path , optional CanvasFillRule fillRule = "nonzero");
undefined stroke ();
undefined stroke (Path2D path );
undefined clip (optional CanvasFillRule fillRule = "nonzero");
undefined clip (Path2D path , optional CanvasFillRule fillRule = "nonzero");
boolean isPointInPath (unrestricted double x , unrestricted double y , optional CanvasFillRule fillRule = "nonzero");
boolean isPointInPath (Path2D path , unrestricted double x , unrestricted double y , optional CanvasFillRule fillRule = "nonzero");
boolean isPointInStroke (unrestricted double x , unrestricted double y );
boolean isPointInStroke (Path2D path , unrestricted double x , unrestricted double y );
};
interface mixin CanvasUserInterface {
undefined drawFocusIfNeeded (Element element );
undefined drawFocusIfNeeded (Path2D path , Element element );
};
interface mixin CanvasText {
// text (see also the CanvasPathDrawingStyles and CanvasTextDrawingStyles interfaces)
undefined fillText (DOMString text , unrestricted double x , unrestricted double y , optional unrestricted double maxWidth );
undefined strokeText (DOMString text , unrestricted double x , unrestricted double y , optional unrestricted double maxWidth );
TextMetrics measureText (DOMString text );
};
interface mixin CanvasDrawImage {
// drawing images
undefined drawImage (CanvasImageSource image , unrestricted double dx , unrestricted double dy );
undefined drawImage (CanvasImageSource image , unrestricted double dx , unrestricted double dy , unrestricted double dw , unrestricted double dh );
undefined drawImage (CanvasImageSource image , unrestricted double sx , unrestricted double sy , unrestricted double sw , unrestricted double sh , unrestricted double dx , unrestricted double dy , unrestricted double dw , unrestricted double dh );
};
interface mixin CanvasImageData {
// pixel manipulation
ImageData createImageData ([EnforceRange ] long sw , [EnforceRange ] long sh , optional ImageDataSettings settings = {});
ImageData createImageData (ImageData imagedata );
ImageData getImageData ([EnforceRange ] long sx , [EnforceRange ] long sy , [EnforceRange ] long sw , [EnforceRange ] long sh , optional ImageDataSettings settings = {});
undefined putImageData (ImageData imagedata , [EnforceRange ] long dx , [EnforceRange ] long dy );
undefined putImageData (ImageData imagedata , [EnforceRange ] long dx , [EnforceRange ] long dy , [EnforceRange ] long dirtyX , [EnforceRange ] long dirtyY , [EnforceRange ] long dirtyWidth , [EnforceRange ] long dirtyHeight );
};
enum CanvasLineCap { "butt" , "round" , "square" };
enum CanvasLineJoin { "round" , "bevel" , "miter" };
enum CanvasTextAlign { " start " , " end " , " left " , " right " , " center " };
enum CanvasTextBaseline { " top " , " hanging " , " middle " , " alphabetic " , " ideographic " , " bottom " };
enum CanvasDirection { " ltr " , " rtl " , " inherit " };
enum CanvasFontKerning { " auto " , " normal " , " none " };
enum CanvasFontStretch { " ultra-condensed " , " extra-condensed " , " condensed " , " semi-condensed " , " normal " , " semi-expanded " , " expanded " , " extra-expanded " , " ultra-expanded " };
enum CanvasFontVariantCaps { " normal " , " small-caps " , " all-small-caps " , " petite-caps " , " all-petite-caps " , " unicase " , " titling-caps " };
enum CanvasTextRendering { " auto " , " optimizeSpeed " , " optimizeLegibility " , " geometricPrecision " };
interface mixin CanvasPathDrawingStyles {
// line caps/joins
attribute unrestricted double lineWidth ; // (default 1)
attribute CanvasLineCap lineCap ; // (default "butt")
attribute CanvasLineJoin lineJoin ; // (default "miter")
attribute unrestricted double miterLimit ; // (default 10)
// dashed lines
undefined setLineDash (sequence <unrestricted double > segments ); // default empty
sequence <unrestricted double > getLineDash ();
attribute unrestricted double lineDashOffset ;
};
interface mixin CanvasTextDrawingStyles {
// text
attribute DOMString font ; // (default 10px sans-serif)
attribute CanvasTextAlign textAlign ; // (default: "start")
attribute CanvasTextBaseline textBaseline ; // (default: "alphabetic")
attribute CanvasDirection direction ; // (default: "inherit")
attribute DOMString letterSpacing ; // (default: "0px")
attribute CanvasFontKerning fontKerning ; // (default: "auto")
attribute CanvasFontStretch fontStretch ; // (default: "normal")
attribute CanvasFontVariantCaps fontVariantCaps ; // (default: "normal")
attribute CanvasTextRendering textRendering ; // (default: "auto")
attribute DOMString wordSpacing ; // (default: "0px")
};
interface mixin CanvasPath {
// shared path API methods
undefined closePath ();
undefined moveTo (unrestricted double x , unrestricted double y );
undefined lineTo (unrestricted double x , unrestricted double y );
undefined quadraticCurveTo (unrestricted double cpx , unrestricted double cpy , unrestricted double x , unrestricted double y );
undefined bezierCurveTo (unrestricted double cp1x , unrestricted double cp1y , unrestricted double cp2x , unrestricted double cp2y , unrestricted double x , unrestricted double y );
undefined arcTo (unrestricted double x1 , unrestricted double y1 , unrestricted double x2 , unrestricted double y2 , unrestricted double radius );
undefined rect (unrestricted double x , unrestricted double y , unrestricted double w , unrestricted double h );
undefined roundRect (unrestricted double x , unrestricted double y , unrestricted double w , unrestricted double h , optional (unrestricted double or DOMPointInit or sequence <(unrestricted double or DOMPointInit )>) radii = 0);
undefined arc (unrestricted double x , unrestricted double y , unrestricted double radius , unrestricted double startAngle , unrestricted double endAngle , optional boolean counterclockwise = false );
undefined ellipse (unrestricted double x , unrestricted double y , unrestricted double radiusX , unrestricted double radiusY , unrestricted double rotation , unrestricted double startAngle , unrestricted double endAngle , optional boolean counterclockwise = false );
};
[Exposed =(Window ,Worker )]
interface CanvasGradient {
// opaque object
undefined addColorStop (double offset , DOMString color );
};
[Exposed =(Window ,Worker )]
interface CanvasPattern {
// opaque object
undefined setTransform (optional DOMMatrix2DInit transform = {});
};
[Exposed =(Window ,Worker )]
interface TextMetrics {
// x-direction
readonly attribute double width ; // advance width
readonly attribute double actualBoundingBoxLeft ;
readonly attribute double actualBoundingBoxRight ;
// y-direction
readonly attribute double fontBoundingBoxAscent ;
readonly attribute double fontBoundingBoxDescent ;
readonly attribute double actualBoundingBoxAscent ;
readonly attribute double actualBoundingBoxDescent ;
readonly attribute double emHeightAscent ;
readonly attribute double emHeightDescent ;
readonly attribute double hangingBaseline ;
readonly attribute double alphabeticBaseline ;
readonly attribute double ideographicBaseline ;
};
dictionary ImageDataSettings {
PredefinedColorSpace colorSpace ;
};
[Exposed =(Window ,Worker ),
Serializable ]
interface ImageData {
constructor (unsigned long sw , unsigned long sh , optional ImageDataSettings settings = {});
constructor (Uint8ClampedArray data , unsigned long sw , optional unsigned long sh , optional ImageDataSettings settings = {});
readonly attribute unsigned long width ;
readonly attribute unsigned long height ;
readonly attribute Uint8ClampedArray data ;
readonly attribute PredefinedColorSpace colorSpace ;
};
[Exposed =(Window ,Worker )]
interface Path2D {
constructor (optional (Path2D or DOMString ) path );
undefined addPath (Path2D path , optional DOMMatrix2DInit transform = {});
};
Path2D includes CanvasPath ;
既存のウェブコンテンツとの互換性を維持するために、ユーザーエージェントはCanvasUserInterfaceに定義されたメソッドをstroke()メソッドの直後にCanvasRenderingContext2Dオブジェクトに列挙する必要があります。
context = canvas.getContext('2d' [, { [ alpha: true ] [, desynchronized: false ] [, colorSpace: 'srgb'] [, willReadFrequently: false ]} ])
CanvasRenderingContext2Dオブジェクトを返し、それは特定のcanvas要素に永久にバインドされます。
もしalphaメンバーがfalseであれば、コンテキストは常に不透明になるように強制されます。
もしdesynchronizedメンバーがtrueであれば、コンテキストはdesynchronizedされる可能性があります。
colorSpaceメンバーは、レンダリングコンテキストの色空間を指定します。
もしwillReadFrequentlyメンバーがtrueであれば、コンテキストは読み取り頻度の最適化のためにマークされます。
context.canvas
CanvasRenderingContext2D/canvas
すべての現行エンジンでサポートされています。
canvas要素を返します。
attributes = context.getContextAttributes()
次のメンバーを持つオブジェクトを返します:
alphaメンバーがtrueである場合、コンテキストにはアルファチャネルがあり、falseである場合、強制的に不透明にされます。
desynchronizedメンバーがtrueである場合、コンテキストはdesynchronizedされる可能性があります。
colorSpaceメンバーがコンテキストの色空間を示す文字列です。
willReadFrequentlyメンバーがtrueである場合、コンテキストは読み取り頻度の最適化のためにマークされます。
CanvasRenderingContext2Dオブジェクトには、オブジェクトが作成されると初期化される出力ビットマップがあります。
出力ビットマップにはorigin-cleanフラグがあり、trueまたはfalseに設定できます。これらのビットマップの1つが作成されると、そのorigin-cleanフラグはtrueに設定されなければなりません。
CanvasRenderingContext2Dオブジェクトには、alphaブール値もあります。CanvasRenderingContext2Dオブジェクトのalphaがfalseである場合、そのアルファチャネルはすべてのピクセルで1.0(完全に不透明)に固定され、任意のピクセルのアルファコンポーネントを変更しようとする試みは静かに無視されます。
したがって、そのようなコンテキストのビットマップは、不透明な黒として開始され、透明な黒ではなく、clearRect()は常に不透明な黒のピクセルを生成し、getImageData()の4バイト目は常に255であり、putImageData()メソッドはその入力の4バイト目を事実上無視します。しかし、キャンバスに描かれたスタイルや画像のアルファコンポーネントは、アルファチャンネルに影響を与える点まで尊重されます。たとえば、出力ビットマップが作成され、そのalphaがfalseに設定されている場合、50%透明な白い四角形を描くと、完全に不透明な灰色の四角形になります。
CanvasRenderingContext2Dオブジェクトには、desynchronizedブール値もあります。CanvasRenderingContext2Dオブジェクトのdesynchronizedがtrueである場合、ユーザーエージェントはキャンバスの描画サイクルをイベントループから切り離し、通常のユーザーエージェントレンダリングアルゴリズムをバイパスするか、両方を行うことによって、入力イベントからラスタライズまでの遅延を減らすためにキャンバスの描画を最適化する場合があります。このモードは、通常のペイントメカニズムやラスタライズ、またはその両方をバイパスすることが含まれるため、視覚的なティアリングアーティファクトを引き起こす可能性があります。
ユーザーエージェントは通常、表示されていないバッファ上でレンダリングを行い、それとスキャンアウト用のバッファをすばやく交換します。前者はバックバッファ、後者はフロントバッファと呼ばれます。遅延を減らすための一般的な技術は、フロントバッファレンダリングとも呼ばれるシングルバッファレンダリングで、レンダリングは並行して、かつ競合的にスキャンアウトプロセスと行われます。この技術は潜在的にティアリングアーティファクトを引き起こす可能性がありますが、desynchronizedブール値の全体または一部の実装に使用することができます。[MULTIPLEBUFFERING]
desynchronizedブール値は、描画アプリケーションのように入力とラスタライズの間の遅延が重要な特定の種類のアプリケーションを実装する際に有用です。
CanvasRenderingContext2Dオブジェクトには、頻繁に読み取るブール値もあります。CanvasRenderingContext2Dオブジェクトの頻繁に読み取るがtrueである場合、ユーザーエージェントは読み取り操作の最適化を行う可能性があります。
ほとんどのデバイスでは、ユーザーエージェントはキャンバスの出力ビットマップをGPU(これは「ハードウェアアクセラレーション」とも呼ばれます)に保存するか、CPU(「ソフトウェア」とも呼ばれます)に保存するかを決定する必要があります。ほとんどの描画操作は加速されたキャンバスでよりパフォーマンスが向上しますが、大きな例外はgetImageData()、toDataURL()、またはtoBlob()での読み戻しです。CanvasRenderingContext2Dオブジェクトで頻繁に読み取るがtrueに設定されている場合、ユーザーエージェントはウェブページが多くの読み戻し操作を行う可能性が高いことを伝え、ソフトウェアキャンバスの使用が有利であることを示します。
CanvasRenderingContext2Dオブジェクトには、色空間設定があり、タイプはPredefinedColorSpaceです。CanvasRenderingContext2Dオブジェクトの色空間は、出力ビットマップの色空間を示します。
getContextAttributes()メソッドのステップは、「alpha"
→ thisのalpha、「desynchronized"
→ thisのdesynchronized、「colorSpace"
→ thisの色空間、「willReadFrequently"
→ thisの頻繁に読み取る」を返します。
CanvasRenderingContext2D
の2Dレンダリングコンテキストは、原点 (0,0) が左上隅にある平坦な線形のデカルト面を表します。座標空間では、x 値は右に進むと増加し、y
値は下に進むと増加します。右端のエッジのx 座標はレンダリングコンテキストの 出力ビットマップ の幅に等しくなり、同様に、下端のエッジのy 座標はレンダリングコンテキストの 出力ビットマップ の高さに等しくなります。この計測はCSSピクセル単位で行われます。
座標空間のサイズは、ユーザーエージェントが内部で使用する実際のビットマップのサイズや、レンダリング中のサイズを必ずしも表すものではありません。例えば、高解像度のディスプレイでは、ユーザーエージェントは座標空間の1ユニットあたり4つのデバイスピクセルを持つビットマップを内部的に使用する場合があり、その結果、レンダリングが高品質に保たれます。同様に、アンチエイリアス処理は、表示される最終画像の解像度よりも高い解像度のビットマップを使用してオーバーサンプリングを行うことで実装されることがあります。
CSSピクセルを使用してレンダリングコンテキストの 出力ビットマップ のサイズを説明することは、キャンバスがレンダリングされたときにCSSピクセルで同等の領域をカバーすることを意味するものではありません。CSSピクセルは、テキストレイアウトなどのCSS機能との統合を容易にするために再利用されています。
言い換えれば、以下のcanvas要素のレンダリングコンテキストは、200x200の出力ビットマップ(内部的には統合を容易にするためにCSSピクセルを単位として使用)を持ち、100x100のCSSピクセルとしてレンダリングされます:
< canvas width = 200 height = 200 style = width:100px;height:100px >
2Dコンテキスト作成アルゴリズムは、target(canvas要素)およびoptionsを受け取り、以下のステップを実行します。
settingsに、変換されたoptionsの辞書型であるCanvasRenderingContext2DSettingsの結果を設定します。(これは例外をスローする可能性があります)。
contextに、新しいCanvasRenderingContext2Dオブジェクトを設定します。
contextのcanvas属性をtargetに設定します。
contextの出力ビットマップをtargetのビットマップと同じものに設定します(これにより、ビットマップが共有されます)。
ビットマップの寸法を設定し、targetのwidthおよびheightコンテンツ属性の数値を取得します。
contextのアルファをsettingsの["alpha"]に設定します。
contextの非同期化をsettingsの["desynchronized"]に設定します。
contextの色空間をsettingsの["colorSpace"]に設定します。
contextの頻繁に読み取られるをsettingsの["willReadFrequently"]に設定します。
contextを返します。
ユーザーエージェントがビットマップの寸法をwidthおよびheightに設定する際は、次のステップを実行する必要があります:
出力ビットマップのサイズを、新しいwidthおよびheightに変更します。
もしcanvasのwidthコンテンツ属性の数値がwidthと異なる場合は、canvasのwidthコンテンツ属性を、widthを有効な非負整数として表す最短の文字列に設定します。
もしcanvasのheightコンテンツ属性の数値がheightと異なる場合は、canvasのheightコンテンツ属性を、heightを有効な非負整数として表す最短の文字列に設定します。
次の例では、1つの四角形のみが描画されているように見えます:
// canvas is a reference to a <canvas> element
var context = canvas. getContext( '2d' );
context. fillRect( 0 , 0 , 50 , 50 );
canvas. setAttribute( 'width' , '300' ); // clears the canvas
context. fillRect( 0 , 100 , 50 , 50 );
canvas. width = canvas. width; // clears the canvas
context. fillRect( 100 , 0 , 50 , 50 ); // only this square remains
canvas属性は、オブジェクトが作成されたときに初期化された値を返さなければなりません。
PredefinedColorSpace列挙型は、キャンバスのバッキングストアのカラースペースを指定するために使用されます。
「srgb」の値は、"srgb"カラースペースを示します。
「display-p3」の値は、"display-p3"カラースペースを示します。
カラースペース間の変換アルゴリズムは、CSS ColorのPredefined color spacesセクションに記載されています。[CSSCOLOR]
CanvasFillRule列挙型は、点がパスの内側か外側かを判断するためのフィルルールアルゴリズムを選択するために使用されます。
「nonzero」の値は、nonzero winding
ruleを示します。このルールでは、ある点がパスを一方向に交差する回数が逆方向に交差する回数と等しい場合、その点は形の外側と見なされます。
「evenodd」の値は、even-odd
ruleを示します。このルールでは、ある点が形のパスを交差する回数が偶数の場合、その点は形の外側と見なされます。
点が形の外側でない場合、それは形の内側にあります。
ImageSmoothingQuality列挙型は、画像のスムージング時に使用する補間品質に対する好みを表現するために使用されます。
「low」の値は、低いレベルの画像補間品質を好むことを示します。低品質の画像補間は、より高い設定よりも計算効率が良い場合があります。
「medium」の値は、中程度のレベルの画像補間品質を好むことを示します。
「high」の値は、高いレベルの画像補間品質を好むことを示します。高品質の画像補間は、低い設定よりも計算コストが高くなる場合があります。
バイリニアスケーリングは、比較的高速な低品質の画像スムージングアルゴリズムの一例です。バイキュービックまたはランチョススケーリングは、より高品質の出力を生成する画像スムージングアルゴリズムの一例です。この仕様では、特定の補間アルゴリズムを使用することを義務付けていません。
このセクションは規範的ではありません。
出力ビットマップがユーザーエージェントによって直接表示されない場合、実装はこのビットマップを更新する代わりに、このビットマップの実際のデータが必要になるまで(例えば、drawImage()やcreateImageBitmap()ファクトリメソッドの呼び出しなど)、それに適用された描画操作のシーケンスを記憶するだけで済ませることができます。多くの場合、これによりメモリ効率が向上します。
canvas要素のビットマップは、実際にはほとんど常に必要とされるビットマップです。レンダリングコンテキストがビットマップを持つ場合、その出力ビットマップは常にcanvas要素のビットマップのエイリアスに過ぎません。
追加のビットマップが必要になることがあります。例えば、キャンバスがその自然サイズとは異なるサイズで描画される場合に高速描画を可能にするため、またはキャンバス描画コマンドが実行されている間にページスクロールなどのグラフィックス更新を並行処理できるようにダブルバッファリングを可能にするためなどです。
CanvasStateインターフェースを実装するオブジェクトは、描画状態のスタックを管理します。描画状態は以下を含みます:
現在の変換行列。
現在のクリッピング領域。
現在の文字間隔、単語間隔、塗りつぶしスタイル、ストロークスタイル、フィルター、グローバルアルファ、合成およびブレンドオペレーター、および影の色。
以下の属性の現在の値:線幅、線端、線結合、マイターリミット、ラインダッシュオフセット、影オフセットX、影オフセットY、影のぼかし、フォント、テキスト整列、テキストベースライン、方向、フォントカーニング、フォントストレッチ、フォントバリアントキャップス、テキストレンダリング、画像スムージング有効、画像スムージング品質。
現在のダッシュリスト。
レンダリングコンテキストのビットマップは描画状態の一部ではありません。これは、レンダリングコンテキストがcanvas要素にどのようにバインドされているかに依存するためです。
CanvasStateミックスインを実装するオブジェクトには、作成時にfalseに初期化されるコンテキストが失われたというブール値があります。このコンテキストが失われた値は、コンテキストが失われたステップで更新されます。
context.save()
現在のすべてのエンジンでサポートされています。
現在の状態をスタックにプッシュします。
context.restore()
CanvasRenderingContext2D/restore
現在のすべてのエンジンでサポートされています。
スタック上の上部状態をポップし、その状態にコンテキストを復元します。
context.reset()
描画状態スタック、パス、スタイルなど、バッキングバッファを含むレンダリングコンテキストをリセットします。
context.isContextLost()
レンダリングコンテキストが失われたかどうかをtrueで返します。ドライバのクラッシュやメモリ不足などによりコンテキストが失われることがあります。このような場合、キャンバスはバッキングストレージを失い、レンダリングコンテキストをデフォルトの状態にリセットする手順を実行します。
save()メソッドの手順は、現在の描画状態のコピーを描画状態スタックにプッシュすることです。
restore()メソッドの手順は、描画状態スタックの上部エントリをポップし、それが示す描画状態にリセットすることです。保存された状態がない場合、このメソッドは何もしません。
CanvasRenderingContext2D/reset
OffscreenCanvasRenderingContext2D#canvasrenderingcontext2d.reset
reset()メソッドの手順は、レンダリングコンテキストをデフォルトの状態にリセットすることです。
レンダリングコンテキストをデフォルトの状態にリセットするには:
キャンバスのビットマップを透明な黒にクリアします。
コンテキストの現在のデフォルトパスのサブパスリストを空にします。
コンテキストの描画状態スタックをクリアします。
描画状態が構成するすべてを初期値にリセットします。
CanvasRenderingContext2D/isContextLost
1つのエンジンのみでサポートされています。
isContextLost()メソッドの手順は、thisのコンテキストが失われた状態を返すことです。
context.lineWidth [ = value ]
CanvasRenderingContext2D/lineWidth
現在のすべてのエンジンでサポートされています。
styles.lineWidth [ = value ]
現在の線の太さを返します。
設定すると、線の太さが変更されます。有限値より大きくない値は無視されます。
context.lineCap [ = value ]
CanvasRenderingContext2D/lineCap
現在のすべてのエンジンでサポートされています。
styles.lineCap [ = value ]
現在の線の端点スタイルを返します。
設定すると、線の端点スタイルが変更されます。
使用可能な線の端点スタイルは "butt"、"round"、および "square" です。他の値は無視されます。
context.lineJoin [ = value ]
CanvasRenderingContext2D/lineJoin
現在のすべてのエンジンでサポートされています。
styles.lineJoin [ = value ]
現在の線の接続スタイルを返します。
設定すると、線の接続スタイルが変更されます。
使用可能な線の接続スタイルは "bevel"、"round"、および "miter" です。他の値は無視されます。
context.miterLimit [ = value ]
CanvasRenderingContext2D/miterLimit
現在のすべてのエンジンでサポートされています。
styles.miterLimit [ = value ]
現在のマイターリミット比を返します。
設定すると、マイターリミット比が変更されます。有限値より大きくない値は無視されます。
context.setLineDash(segments)
CanvasRenderingContext2D/setLineDash
現在のすべてのエンジンでサポートされています。
styles.setLineDash(segments)
現在の線の破線パターン(ストロークに使用される)を設定します。引数は、線をオンにしてオフにする距離のリストです。
segments = context.getLineDash()
CanvasRenderingContext2D/getLineDash
現在のすべてのエンジンでサポートされています。
segments = styles.getLineDash()
現在の線の破線パターンのコピーを返します。返される配列には、常に偶数のエントリがあります(つまり、パターンは正規化されます)。
context.lineDashOffset
CanvasRenderingContext2D/lineDashOffset
現在のすべてのエンジンでサポートされています。
styles.lineDashOffset
(線の破線パターンと同じ単位での)位相オフセットを返します。
設定すると、位相オフセットが変更されます。有限値でない値は無視されます。
CanvasPathDrawingStyles
インターフェースを実装するオブジェクトには、このセクションで定義された属性やメソッドがあり、オブジェクトによって線がどのように扱われるかを制御します。
lineWidth
属性は、線の幅を座標空間単位で指定します。取得時には現在の値を返さなければなりません。設定時には、ゼロ、負の値、無限、NaN の値は無視され、値は変更されません。その他の値は現在の値を新しい値に変更しなければなりません。
CanvasPathDrawingStyles
インターフェースを実装するオブジェクトが作成されると、 lineWidth 属性は初期値 1.0
を持たなければなりません。
lineCap 属性は、ユーザーエージェントが線の終端に置くエンドポイントのタイプを定義します。 有効な3つの値は
"butt"、"round"、および "square" です。
取得時には現在の値を返さなければなりません。設定時には現在の値を新しい値に変更しなければなりません。
CanvasPathDrawingStyles
インターフェースを実装するオブジェクトが作成されると、 lineCap 属性は初期値
"butt" を持たなければなりません。
lineJoin 属性は、2つの線が交わる場所にユーザーエージェントが配置するコーナーのタイプを定義します。 有効な3つの値は
"bevel"、"round"、および "miter" です。
取得時には現在の値を返さなければなりません。設定時には現在の値を新しい値に変更しなければなりません。
CanvasPathDrawingStyles
インターフェースを実装するオブジェクトが作成されると、 lineJoin 属性は初期値
"miter" を持たなければなりません。
lineJoin 属性が
"miter" の値を持つ場合、ストロークはマイターリミット比を使用してジョインの描画方法を決定します。 マイターリミット比は、miterLimit
属性を使用して明示的に設定できます。取得時には現在の値を返さなければなりません。設定時には、ゼロ、負の値、無限、NaN の値は無視され、値は変更されません。その他の値は現在の値を新しい値に変更しなければなりません。
CanvasPathDrawingStyles
インターフェースを実装するオブジェクトが作成されると、 miterLimit 属性は初期値
10.0 を持たなければなりません。
各 CanvasPathDrawingStyles
オブジェクトには ダッシュリスト があり、それは空であるか、正の数の偶数個の数字で構成されるものです。最初は ダッシュリスト が空でなければなりません。
setLineDash(segments) メソッドが呼び出されると、次の手順を実行しなければなりません:
segments 内のいずれかの値が有限でない場合 (例えば無限や NaN 値) 、または値が負である場合 (0 未満の場合) 、終了しなければなりません(例外をスローせずに;デベロッパーコンソールにメッセージを表示することはデバッグに役立つため推奨されます)。
segments の要素数が奇数の場合、segments を segments の2つのコピーで連結しなければなりません。
オブジェクトの ダッシュリスト を segments に設定しなければなりません。
getLineDash() メソッドが呼び出されると、オブジェクトの ダッシュリスト の値を同じ順序で含む配列を返さなければなりません。
ダッシュパターンの「フェーズ」を変更することは、時々便利です。例えば、「行進するアリ」のような効果を達成するために。フェーズは、lineDashOffset
属性を使用して設定できます。取得時には現在の値を返さなければなりません。設定時には、無限および NaN 値は無視され、値は変更されません。その他の値は現在の値を新しい値に変更しなければなりません。
CanvasPathDrawingStyles
インターフェースを実装するオブジェクトが作成されると、lineDashOffset
属性は初期値 0.0 を持たなければなりません。
ユーザーエージェントがパスをトレースする場合、CanvasPathDrawingStyles
インターフェースを実装するオブジェクト style が与えられた場合、次のアルゴリズムを実行しなければなりません。このアルゴリズムは、新しい パス を返します。
トレースされるパスのコピーをpath とします。
path からすべてのゼロ長の 線分 を除去します。
path から線を含まないすべてのサブパス(つまり、1つの点のみを持つサブパス)を削除します。
path の各サブパスの最初の点と最後の点以外の各点を、それぞれの点から出ている線と、出ている線を結ぶ ジョイン に置き換えます。サブパスはすべて2つの点(それぞれ出発点と終点)と、それぞれの点を結ぶ線(またはジョイン)で構成されており、サブパスは一連の線とジョインで結ばれています。
サブパスの最後の点と最初の点を結ぶ直線を追加し、最後の点をジョインに変更します(追加された閉じる線から出発する線に接続)。最初の点もジョインに変更します(追加された閉じる線と最初の線を結ぶジョインとして)。
style の ダッシュリスト が空の場合、変換 というラベルが付いたステップにジャンプします。
pattern width をstyle の ダッシュリスト のすべてのエントリの連結とします(座標空間単位で)。
path の各サブパス subpath に対して、次のサブステップを実行します。これらのサブステップは path のサブパスを インビボ で変異させます。
subpath width を、subpath のすべての線の長さとします(座標空間単位で)。
offset をstyle の lineDashOffset
の値とします(座標空間単位で)。
offset が pattern width を超える場合、pattern width を減算します。
offset が 0 未満の場合、pattern width を加算します。
すべての線を含む subpath に沿った線形座標線 L を定義し、サブパスの最初の線の開始点を座標 0、サブパスの最後の線の終了点を subpath width として定義します。
position を 0 からoffset 減じた値とします。
index を 0 とします。
current state を オフ (他の状態はオンとゼロオン)とします。
ダッシュオン: segment length を style の ダッシュリスト の index 番目のエントリとします。
position を segment length だけ増やします。
position が subpath width を超える場合、このサブパスに対するサブステップを終了し、次のサブパスに対して再度開始します。サブパスがない場合、変換 というラベルが付いたステップにジャンプします。
segment length がゼロでない場合、current state を オン にします。
index を 1 増やします。
ダッシュオフ: segment length を style の ダッシュリスト の index 番目のエントリとします。
start を L 上の position のオフセットとします。
position を segment length だけ増やします。
position が 0 未満の場合、ポストカット というラベルが付いたステップにジャンプします。
start が 0 未満の場合、start を 0 とします。
position が subpath width を超える場合、end を L 上の subpath width のオフセットとします。それ以外の場合、end を L 上の position のオフセットとします。
次の適切なステップにジャンプします:
何もしません。そのまま次のステップに進みます。
end のある線を end で短く切り、そこで点を配置し、元のサブパスを2つに分割します。 start と end の間のすべての線分、ジョイン、点、およびサブパスを削除します。そして、最終的に start に単一の点を配置し、その点に接続する線はありません。
その点は線の端点の描画に関して 方向性 を持っています(上記の L の定義時に)。
start のある線を2つに分割し、そこに点を配置します。元のサブパスを2つに分割し、同様に end のある線を end で短く切り、そこで点を配置します。元のサブパスを2つに分割し、そして start と end の間のすべての線分、ジョイン、点、およびサブパスを削除します。
start と end が同じ点である場合、これにより線が2つに分割され、その点に2つの点が挿入されるだけで、何も削除されません。ただし、その点にジョインもある場合は、ジョインが削除されなければなりません。
ポストカット: position が subpath width を超える場合、変換 というラベルが付いたステップにジャンプします。
segment length が 0 より大きい場合、positioned-at-on-dash を false にします。
index を 1 増やします。 style の ダッシュリスト のエントリ数と等しい場合、index を 0 に設定します。
ダッシュオン というラベルが付いたステップに戻ります。
変換: これは、パスを新しいパスに変換するステップです。
新しい パス を作成します。これは path
の各サブパスに沿って、style の lineWidth
に等しい長さの直線が掃引され、その線がパスに対して直角に保たれるようにし、各点を満たすために必要なエンドキャップを追加し、各ジョインを満たすために必要なジョインを追加したパスを記述します。
キャップ: 各点には、その点から出る線の方向に直角の平らな縁があります。これに style の lineCap
の値に従って、さらに追加されます。 "butt" の値は、追加のラインキャップが追加されないことを意味します。 "round" の値は、
style の lineWidth
の幅に等しい直径の半円を点から出る線に追加する必要があることを意味します。 "square" の値は、 style の lineWidth
の幅の長さと、幅の半分の style の lineWidth
幅の長方形を追加する必要があり、それが点から出る線に直角に接するように配置されます。
線が出ていない点には、その点が本当に2つの点で、点の方向性に向かって無限に短い直線で接続されているかのように、2つのキャップが背中合わせに配置されなければなりません。
ジョイン: ジョインが発生する点に加えて、ジョインに関連する2つの追加の点があり、各線に1つずつあります。これらは、ジョイン点から各線に直角に、各線から最も遠い側にある2つの角です。
この2つの角を直線で結び、三角形の第3の点をジョイン点とし、すべてのジョインでこの三角形を追加しなければなりません。 lineJoin
属性は、ジョインで他に何がレンダリングされるかを制御します。これらの3つの値は次の意味を持ちます:
"bevel" の値は、ジョインでこれだけがレンダリングされることを意味します。
"round"
の値は、ジョインの2つの角を結ぶ弧を追加し、その弧は前述の三角形に接するものであり、直径が線の幅に等しく、ジョイン点を中心とするものでなければならないことを意味します。
"miter"
の値は、ジョインで2番目の三角形を(可能であれば)追加しなければならないことを意味します。この三角形の1つの辺は2つの角を結ぶ線であり、最初の三角形に接し、他の2つの辺は接続している2本の線の外側の縁を延長したものであり、必要に応じてミーターの長さを超えないようにする必要があります。
ミーターの長さは、ジョインが発生する点からジョインの外側の線の縁の交点までの距離です。マイターリミット比は、ミーターの長さと線の幅の半分の比率の最大許容値です。ミーターの長さが style
の miterLimit
属性によって設定されたマイターリミット比を超える場合、この2番目の三角形は追加されないようにしなければなりません。
新しく作成されたパス内のサブパスは、任意の点に対して、その点から引かれる半無限直線がサブパスを交差する回数が偶数であり、その点から引かれる半無限直線がサブパスを一方向に交差する回数が他の方向に交差する回数と等しい場合に限り、そのサブパスの交差回数が偶数であるように配置しなければなりません。
新しく作成されたパスを返します。
context.font [ = value ]
すべての現行エンジンでサポートされています。
styles.font [ = value ]
現在のフォント設定を返します。
設定すると、フォントが変更されます。構文は CSS の 'font' プロパティと同じです。CSS フォント値として解析できない値は無視されます。
相対的なキーワードと長さは、canvas
要素のフォントを基準に計算されます。
context.textAlign [ = value ]
CanvasRenderingContext2D/textAlign
すべての現行エンジンでサポートされています。
styles.textAlign [ = value ]
現在のテキスト整列設定を返します。
設定すると、整列が変更されます。可能な値とその意味は以下に示されています。他の値は無視されます。デフォルトは「start」です。
context.textBaseline [ = value ]
CanvasRenderingContext2D/textBaseline
すべての現行エンジンでサポートされています。
styles.textBaseline [ = value ]
現在のベースライン整列設定を返します。
設定すると、ベースライン整列が変更されます。可能な値とその意味は以下に示されています。他の値は無視されます。デフォルトは「alphabetic」です。
context.direction [ = value ]
CanvasRenderingContext2D/direction
すべての現行エンジンでサポートされています。
styles.direction [ = value ]
現在の方向性を返します。
設定すると、方向性が変更されます。可能な値とその意味は以下に示されています。他の値は無視されます。デフォルトは「inherit」です。
context.letterSpacing [ = value ]
styles.letterSpacing [ = value ]
現在の文字間隔を返します。
設定すると、文字間隔が変更されます。CSS の <length> として解析できない値は無視されます。デフォルトは「0px」です。
context.fontKerning [ = value ]
styles.fontKerning [ = value ]
現在のフォントカーニング設定を返します。
設定すると、フォントカーニングが変更されます。可能な値とその意味は以下に示されています。他の値は無視されます。デフォルトは「auto」です。
context.fontStretch [ = value ]
styles.fontStretch [ = value ]
現在のフォントストレッチ設定を返します。
設定すると、フォントストレッチが変更されます。可能な値とその意味は以下に示されています。他の値は無視されます。デフォルトは「normal」です。
context.fontVariantCaps [ = value ]
styles.fontVariantCaps [ = value ]
現在のフォントバリアントキャップス設定を返します。
設定すると、フォントバリアントキャップスが変更されます。可能な値とその意味は以下に示されています。他の値は無視されます。デフォルトは「normal」です。
context.textRendering [ = value ]
styles.textRendering [ = value ]
現在のテキストレンダリング設定を返します。
設定すると、テキストレンダリングが変更されます。可能な値とその意味は以下に示されています。他の値は無視されます。デフォルトは「auto」です。
context.wordSpacing [ = value ]
styles.wordSpacing [ = value ]
現在の単語間隔を返します。
設定すると、単語間隔が変更されます。CSS の <length> として解析できない値は無視されます。デフォルトは「0px」です。
CanvasTextDrawingStyles
インターフェースを実装するオブジェクトには、オブジェクトがテキストをどのようにレイアウトするか(ラスタライズまたはアウトライン化)を制御する属性(このセクションで定義されています)が備わっています。これらのオブジェクトには、フォントスタイルソースオブジェクトも持つことができます。CanvasRenderingContext2Dオブジェクトの場合、これはコンテキストのcanvas要素であり、コンテキストのcanvas属性の値によって指定されます。OffscreenCanvasRenderingContext2Dオブジェクトの場合、これは関連するOffscreenCanvasオブジェクトです。
フォントスタイルソースオブジェクトのフォント解像度には、フォントソースが必要です。これは、CanvasTextDrawingStylesを実装する特定のobjectに対して、次のステップで決定されます:[CSSFONTLOAD]
objectのフォントスタイルソースオブジェクトがcanvas要素である場合、その要素のノードドキュメントを返します。
それ以外の場合、objectのフォントスタイルソースオブジェクトはOffscreenCanvasオブジェクトです:
globalをobjectの関連するグローバルオブジェクトに設定します。
globalがWindowオブジェクトである場合、globalの関連するDocumentを返します。
アサート: globalがWorkerGlobalScopeを実装していることを確認します。
globalを返します。
これは、ID c1 を持つ通常の canvas 要素を使用したフォント解像度の例です。
const font = new FontFace( "MyCanvasFont" , "url(mycanvasfont.ttf)" );
documents. fonts. add( font);
const context = document. getElementById( "c1" ). getContext( "2d" );
document. fonts. ready. then( function () {
context. font = "64px MyCanvasFont" ;
context. fillText( "hello" , 0 , 0 );
});
この例では、canvas はフォントとして mycanvasfont.ttf を使用してテキストを表示します。
これは、OffscreenCanvasを使用してフォント解像度がどのように行われるかの例です。
ID canvas 要素があり、
これを以下のようにワーカーに転送することを前提としています:
const offscreenCanvas = document. getElementById( "c2" ). transferControlToOffscreen();
worker. postMessage( offscreenCanvas, [ offscreenCanvas]);
次に、ワーカー内で:
self. onmessage = function ( ev) {
const transferredCanvas = ev. data;
const context = transferredCanvas. getContext( "2d" );
const font = new FontFace( "MyFont" , "url(myfont.ttf)" );
self. fonts. add( font);
self. fonts. ready. then( function () {
context. font = "64px MyFont" ;
context. fillText( "hello" , 0 , 0 );
});
};
この例では、canvas は myfont.ttf を使用してテキストを表示します。
フォントはドキュメントのコンテキストではなく、ワーカー内でのみロードされる点に注意してください。
font
IDL 属性は、設定時にCSS <'font'> 値として解析
されなければならず(ただし、「inherit」のようなプロパティに依存しないスタイルシート構文はサポートしません)、その結果として得られるフォントはコンテキストに割り当てられ、'line-height' のコンポーネントは「normal」に強制され、
'font-size' のコンポーネントはCSS
ピクセルに変換され、システムフォントは明示的な値に計算されます。新しい値が文法的に誤っている場合(「inherit」や「initial」のようなプロパティに依存しないスタイルシート構文を使用している場合を含む)、新しいフォント値を割り当てることなく無視しなければなりません。[CSS]
フォントファミリ名は、フォントが使用されるときにフォントスタイルソースオブジェクトのコンテキストで解釈される必要があります。そのため、@font-faceを使用して埋め込まれたフォントや、
フォントスタイルソースオブジェクト
に表示されるFontFaceオブジェクトを使用してロードされたフォントは、ロードされると利用可能でなければなりません。(各フォントスタイルソースオブジェクトには、利用可能なフォントを決定するフォントソースがあります。)フォントが完全にロードされる前に使用された場合、またはそのフォントが使用される時点でフォントスタイルソースオブジェクトに範囲内にない場合は、それが未知のフォントとして扱われ、関連するCSS仕様書で説明されているように他のフォントにフォールバックしなければなりません。[CSSFONTS] [CSSFONTLOAD]
取得時には、font
属性は、コンテキストの現在のフォントのシリアライズされた形式
を返さなければなりません('line-height' コンポーネントは含みません)。[CSSOM]
たとえば、次の文の後:
context. font = 'italic 400 12px/2 Unknown Font, sans-serif' ;
...この式 context.font は文字列 "italic 12px "Unknown Font", sans-serif" に評価されます。"400"
フォントウェイトはデフォルト値であるため表示されません。行の高さは「normal」(デフォルト値)に強制されるため表示されません。
CanvasTextDrawingStyles
インターフェイスを実装するオブジェクトが作成されたとき、コンテキストのフォントは10pxのsans-serifに設定されなければなりません。'font-size'コンポーネントがパーセンテージ、'em'または'ex'単位、または「larger」や「smaller」のキーワードを使用して長さが設定された場合、これらは計算値
に対して解釈される必要があります。
'font-size'プロパティの属性が設定された時点でのフォントスタイルソースオブジェクトの計算値が未定義の場合(例えば、フォントスタイルソースオブジェクトが
要素ではないか、レンダリングされていないため)、相対的なキーワードは10pxのsans-serifのデフォルトに対して解釈されなければなりません。
textAlign IDL
属性は、取得時に現在の値を返さなければなりません。設定時には、現在の値を新しい値に変更しなければなりません。CanvasTextDrawingStylesインターフェイスを実装するオブジェクトが作成されるとき、textAlign属性は初期値としてstartの値を持たなければなりません。
textBaseline IDL
属性は、取得時に現在の値を返さなければなりません。設定時には、現在の値を新しい値に変更しなければなりません。CanvasTextDrawingStylesインターフェイスを実装するオブジェクトが作成されるとき、textBaseline属性は初期値としてalphabeticの値を持たなければなりません。
direction IDL
属性は、取得時に現在の値を返さなければなりません。設定時には、現在の値を新しい値に変更しなければなりません。CanvasTextDrawingStylesインターフェイスを実装するオブジェクトが作成されるとき、direction属性は初期値として"inherit"の値を持たなければなりません。
CanvasTextDrawingStylesインターフェイスを実装するオブジェクトには、文字と単語の間隔を制御する属性があります。このようなオブジェクトには、関連付けられた文字間隔および単語間隔の値があり、これらはCSSの<length>値です。初期値として、両方ともCSSの"0px"を解析した結果でなければなりません。
CanvasRenderingContext2D/letterSpacing
1つのエンジンでのみサポートされています。
letterSpacingのgetterステップは、
シリアライズされた形式
を返すことです。thisの文字間隔を返します。
letterSpacingのsetterステップは以下の通りです:
CanvasRenderingContext2D/wordSpacing
1つのエンジンでのみサポートされています。
wordSpacingのgetterステップは、
シリアライズされた形式
を返すことです。thisの単語間隔を返します。
wordSpacingのsetterステップは以下の通りです:
CanvasRenderingContext2D/fontKerning
fontKerning IDL
属性は、取得時に現在の値を返さなければなりません。設定時には、現在の値を新しい値に変更しなければなりません。CanvasTextDrawingStylesインターフェイスを実装するオブジェクトが作成されるとき、fontKerning属性は初期値として"auto"の値を持たなければなりません。
CanvasRenderingContext2D/fontStretch
1つのエンジンでのみサポートされています。
fontStretch IDL
属性は、取得時に現在の値を返さなければなりません。設定時には、現在の値を新しい値に変更しなければなりません。CanvasTextDrawingStylesインターフェイスを実装するオブジェクトが作成されるとき、fontStretch属性は初期値として"normal"の値を持たなければなりません。
CanvasRenderingContext2D/fontVariantCaps
1つのエンジンでのみサポートされています。
fontVariantCaps IDL
属性は、取得時に現在の値を返さなければなりません。設定時には、現在の値を新しい値に変更しなければなりません。CanvasTextDrawingStylesインターフェイスを実装するオブジェクトが作成されるとき、fontVariantCaps属性は初期値として"normal"の値を持たなければなりません。
CanvasRenderingContext2D/textRendering
1つのエンジンでのみサポートされています。
textRendering IDL
属性は、取得時に現在の値を返さなければなりません。設定時には、現在の値を新しい値に変更しなければなりません。CanvasTextDrawingStylesインターフェイスを実装するオブジェクトが作成されるとき、textRendering属性は初期値として"auto"の値を持たなければなりません。
textAlign属性で許可されるキーワードは以下の通りです:
start
テキストの開始端に揃えます(左から右のテキストでは左側、右から左のテキストでは右側)。
end
テキストの終了端に揃えます(左から右のテキストでは右側、右から左のテキストでは左側)。
left
左揃えにします。
right
右揃えにします。
center
中央揃えにします。
textBaseline属性で許可されるキーワードは、フォント内の整列ポイントに対応しています:

キーワードは次のようにこれらの整列ポイントに対応します:
top
hanging
middle
alphabetic
ideographic
bottom
direction属性で許可されるキーワードは以下の通りです:
ltr
テキスト準備アルゴリズムへの入力を左から右のテキストとして扱います。
rtl
テキスト準備アルゴリズムへの入力を右から左のテキストとして扱います。
inherit
fontKerning属性で許可されるキーワードは以下の通りです:
auto
カーニングはユーザーエージェントの裁量で適用されます。
normal
カーニングが適用されます。
none
カーニングは適用されません。
fontStretch属性で許可されるキーワードは以下の通りです:
ultra-condensed
CSSの'font-stretch'設定である'ultra-condensed'と同じです。
extra-condensed
CSSの'font-stretch'設定である'extra-condensed'と同じです。
condensed
CSSの'font-stretch'設定である'condensed'と同じです。
semi-condensed
CSSの'font-stretch'設定である'semi-condensed'と同じです。
normal
デフォルトの設定で、グリフの幅は100%になります。
semi-expanded
CSSの'font-stretch'設定である'semi-expanded'と同じです。
expanded
CSSの'font-stretch'設定である'expanded'と同じです。
extra-expanded
CSSの'font-stretch'設定である'extra-expanded'と同じです。
ultra-expanded
CSSの'font-stretch'設定である'ultra-expanded'と同じです。
fontVariantCaps属性で許可されるキーワードは以下の通りです:
normal
以下に挙げる機能は有効化されません。
small-caps
CSSの'font-variant-caps'設定である'small-caps'と同じです。
all-small-caps
CSSの'font-variant-caps'設定である'all-small-caps'と同じです。
petite-caps
CSSの'font-variant-caps'設定である'petite-caps'と同じです。
all-petite-caps
CSSの'font-variant-caps'設定である'all-petite-caps'と同じです。
unicase
CSSの'font-variant-caps'設定である'unicase'と同じです。
titling-caps
CSSの'font-variant-caps'設定である'titling-caps'と同じです。
textRendering属性で許可されるキーワードは以下の通りです:
auto
SVGのテキストレンダリングプロパティにおける「auto」と同じです。
optimizeSpeed
SVGのテキストレンダリングプロパティにおける「optimizeSpeed」と同じです。
optimizeLegibility
SVGのテキストレンダリングプロパティにおける「optimizeLegibility」と同じです。
geometricPrecision
SVGのテキストレンダリングプロパティにおける「geometricPrecision」と同じです。
テキスト準備アルゴリズムは次の通りです。文字列text、CanvasTextDrawingStylesオブジェクトtarget、および任意の長さmaxWidthを入力として受け取り、グリフ形状の配列を共通の座標空間に配置し、left、right、centerのいずれかの値を持つ物理的な整列、およびインラインボックスを返します。(このアルゴリズムを呼び出すほとんどのコール元は、物理的な整列とインラインボックスを無視します。)
maxWidthが指定されており、0以下またはNaNである場合、空の配列を返します。
text内のASCII空白をすべてU+0020 SPACE文字に置き換えます。
targetオブジェクトのfont属性によって与えられる現在のフォントをfontとします。
次のリストから適切なステップを適用してdirectionの値を決定します:
direction属性が"ltr"である場合
direction属性が"rtl"である場合
Documentであり、nullでないドキュメント要素を持っている場合
単一のインラインボックスを含む仮想的に無限に広いCSSラインボックスを形成し、そのCSSプロパティを以下のように設定します:
| プロパティ | ソース |
|---|---|
| 'direction' | direction |
| 'font' | font |
| 'font-kerning' | targetのfontKerning
|
| 'font-stretch' | targetのfontStretch
|
| 'font-variant-caps' | targetのfontVariantCaps
|
| 'letter-spacing' | targetのletter spacing |
| SVGテキストレンダリング | targetのtextRendering
|
| 'white-space' | 'pre' |
| 'word-spacing' | targetのword spacing |
その他のすべてのプロパティは初期値に設定します。
maxWidthが指定されており、仮想的なインラインボックス内の仮想的なラインボックスの幅がmaxWidthのCSSピクセルを超える場合、フォントをより凝縮したものに変更する(使用可能な場合、または水平スケールファクターを適用して読みやすいものが合成できる場合)か、より小さいフォントに変更し、前のステップに戻ります。
アンカーポイントはインラインボックス上のポイントであり、物理的な整列はleft、right、およびcenterの値のいずれかです。これらの変数はtextAlignおよびtextBaselineの値によって次のように決定されます:
水平位置:
textAlignがleftである場合
textAlignがstartであり、directionが'ltr'である場合
textAlignがendであり、directionが'rtl'である場合
textAlignがrightである場合
textAlignがendであり、directionが'ltr'である場合
textAlignがstartであり、directionが'rtl'である場合
textAlignがcenterである場合
垂直位置:
textBaselineがtopである場合
textBaselineがhangingである場合
textBaselineがmiddleである場合
textBaselineがalphabeticである場合
textBaselineがideographicである場合
textBaselineがbottomである場合
resultを配列として、左から右(存在する場合)にインラインボックス内の各グリフを反復し、各グリフの形状をアンカーポイントに原点を持つ座標空間に配置された状態で配列に追加することで構成します。
result、物理的な整列、およびインラインボックスを返します。
CanvasPathインターフェースを実装するオブジェクトは、パスを持ちます。パスは、0個以上のサブパスのリストを持ちます。各サブパスは、直線または曲線の線分で接続された1つ以上の点と、そのサブパスが閉じているかどうかを示すフラグで構成されます。サブパスが閉じている場合、サブパスの最後の点は、直線でサブパスの最初の点に接続されます。1つの点しか持たないサブパスは、パスを描画する際に無視されます。
パスには新しいサブパスが必要というフラグがあります。このフラグが設定されると、特定のAPIは前のサブパスを拡張するのではなく、新しいサブパスを作成します。パスが作成されるとき、その新しいサブパスが必要というフラグが設定されなければなりません。
CanvasPathインターフェースを実装するオブジェクトが作成されると、そのパスは0個のサブパスに初期化されなければなりません。
context.moveTo(x, y)
CanvasRenderingContext2D/moveTo
すべての現行エンジンでサポートされています。
指定された点で新しいサブパスを作成します。
context.closePath()
CanvasRenderingContext2D/closePath
すべての現行エンジンでサポートされています。
現在のサブパスを閉じたものとしてマークし、新しく閉じられたサブパスの開始点と終了点が同じ点で新しいサブパスを開始します。
context.lineTo(x, y)
CanvasRenderingContext2D/lineTo
すべての現行エンジンでサポートされています。
指定された点を現在のサブパスに追加し、前の点と直線で接続します。
context.quadraticCurveTo(cpx, cpy, x, y)
CanvasRenderingContext2D/quadraticCurveTo
すべての現行エンジンでサポートされています。
指定された点を現在のサブパスに追加し、指定された制御点で二次ベジェ曲線で接続します。
context.bezierCurveTo(cp1x, cp1y, cp2x, cp2y, x, y)
CanvasRenderingContext2D/bezierCurveTo
すべての現行エンジンでサポートされています。
指定された点を現在のサブパスに追加し、指定された制御点で三次ベジェ曲線で接続します。
context.arcTo(x1, y1, x2, y2, radius)
CanvasRenderingContext2D/arcTo
すべての現行エンジンでサポートされています。
指定された制御点と半径で現在のサブパスに円弧を追加し、前の点と直線で接続します。
指定された半径が負の場合、"IndexSizeError" DOMExceptionをスローします。
context.arc(x, y, radius, startAngle, endAngle [, counterclockwise ])
すべての現行エンジンでサポートされています。
指定された点、半径、開始角度、終了角度、方向に基づいて、円弧を現在のサブパスに追加します。
指定された半径が負の場合、"IndexSizeError" DOMExceptionをスローします。
context.ellipse(x, y, radiusX, radiusY, rotation, startAngle, endAngle [, counterclockwise])
CanvasRenderingContext2D/ellipse
すべての現行エンジンでサポートされています。
指定された点、x方向の半径、y方向の半径、回転角、開始角度、終了角度、方向に基づいて、楕円弧を現在のサブパスに追加します。
指定された半径が負の場合、"IndexSizeError" DOMExceptionをスローします。
context.rect(x, y, w, h)
すべての現行エンジンでサポートされています。
指定された四角形を表す新しい閉じたサブパスをパスに追加します。
context.roundRect(x, y, w, h, radii)
path.roundRect(x, y, w, h, radii)
指定された角の半径を持つ四角形を表す新しい閉じたサブパスをパスに追加します。radiiは、四角形の角を表すピクセル単位の半径のリストか、1つの半径を表す単一の値のいずれかです。リストが提供された場合、これらの半径の数と順序はCSSの'border-radius'プロパティと同じように機能します。単一の半径は、1つの要素を持つリストと同じように機能します。
wとhの両方が0以上または両方が0未満の場合、パスは時計回りに描画されます。それ以外の場合、反時計回りに描画されます。
wが負の場合、角丸の四角形は水平に反転されます。これにより、通常は左の角に適用される半径の値が右に使用され、その逆も同様です。同様に、hが負の場合、角丸の四角形は垂直に反転されます。
radii内のrの値が数値である場合、対応する角は半径rの円弧として描かれます。
radii内のrの値が{ x, y }プロパティを持つオブジェクトである場合、対応する角は、それぞれr.xとr.yに等しいxとyの半径を持つ楕円弧として描かれます。
同じエッジの2つの角のradiiの合計がエッジの長さを超える場合、角丸の四角形のすべてのradiiは長さ/(r1 + r2)の係数でスケーリングされます。複数のエッジがこのプロパティを持つ場合、最小のスケール係数を持つエッジのスケール係数が使用されます。これはCSSの動作と一致します。
radiiが1つ、2つ、3つ、または4つでないリストである場合、RangeErrorをスローします。
radii内の値が負の数である場合、または{ x, y }オブジェクトでxまたはyプロパティが負の数である場合、RangeErrorをスローします。
次のメソッドを使用すると、著者は CanvasPath
インターフェイスを実装するオブジェクトのパスを操作できます。
CanvasDrawPath および CanvasTransform
インターフェイスを実装するオブジェクトの場合、メソッドに渡されるポイントおよびこれらのメソッドによって現在のデフォルトパスに追加される結果としてのラインは、パスに追加される前に現在の変換行列に従って変換される必要があります。
moveTo(x, y)メソッドが呼び出されたとき、次の手順を実行する必要があります:
引数のいずれかが無限大またはNaNである場合は、終了します。
指定されたポイントを最初の(および唯一の)ポイントとする新しいサブパスを作成します。
ユーザーエージェントが座標 (x, y) に対してサブパスが存在することを確認する必要がある場合、パスが新しいサブパスが必要フラグを持っているかどうかを確認する必要があります。もしフラグが設定されている場合、ユーザーエージェントは、moveTo()メソッドが呼び出されたかのように、座標
(x, y) を最初の(そして唯一の)点とする新しいサブパスを作成し、その後、パスの新しいサブパスが必要フラグを解除する必要があります。
closePath()メソッドが呼び出されたとき、オブジェクトのパスにサブパスがない場合は何も行わない必要があります。そうでない場合、最後のサブパスを閉じ、前のサブパスの最初のポイントと同じポイントを持つ新しいサブパスを作成し、この新しいサブパスをパスに追加する必要があります。
最後のサブパスにリスト内に複数のポイントがある場合、これは最後のサブパスの最後のポイントを最初のポイントに接続する直線を追加するのと同等であり、したがってサブパスを「閉じる」ことになります。
新しいポイントとそれらを接続するラインは、以下に記載されているメソッドを使用してサブパスに追加されます。すべての場合において、メソッドはオブジェクトのパス内の最後のサブパスのみを変更します。
lineTo(x, y)メソッドが呼び出されたとき、次の手順を実行する必要があります:
引数のいずれかが無限大またはNaNである場合は、終了します。
オブジェクトのパスにサブパスが存在しない場合は、サブパスが存在することを確認する (x, y)。
そうでない場合、最後のポイントを指定されたポイント(x, y)に直線で接続し、その後、指定されたポイント(x, y)をサブパスに追加します。
quadraticCurveTo(cpx, cpy, x, y)メソッドが呼び出されたとき、次の手順を実行する必要があります:
引数のいずれかが無限大またはNaNである場合は、終了します。
サブパスがあることを確認します。指定された制御点(cpx, cpy)。
最後のポイントを指定されたポイント(x, y)に指定された制御点(cpx, cpy)でベジエ曲線を使用して接続し、指定されたポイント(x, y)をサブパスに追加します。
bezierCurveTo(cp1x, cp1y, cp2x, cp2y, x, y)メソッドが呼び出されたとき、次の手順を実行する必要があります:
引数のいずれかが無限大またはNaNである場合は、終了します。
サブパスがあることを確認します。指定された制御点(cp1x, cp1y)。
最後のポイントを指定されたポイント(x, y)に指定された制御点(cp1x, cp1y)および(cp2x, cp2y)でベジエ曲線を使用して接続し、指定されたポイント(x, y)をサブパスに追加します。
arcTo(x1, y1, x2, y2, radius)メソッドが呼び出されたとき、次の手順を実行する必要があります:
引数のいずれかが無限大またはNaNである場合は、終了します。
サブパスがあることを確認します。指定されたポイント(x1, y1)。
radiusが負の場合、"IndexSizeError"DOMExceptionをスローします。
ポイント(x0, y0)を最後のサブパスのポイントとし、現在の変換行列の逆数で変換された座標系で、メソッドに渡されたポイントと同じ座標系にします。
ポイント(x0, y0)がポイント(x1, y1)と等しい場合、またはポイント(x1, y1)がポイント(x2, y2)と等しい場合、またはradiusがゼロの場合、ポイント(x1, y1)をサブパスに追加し、そのポイントを前のポイント(x0, y0)と直線で接続します。
それ以外の場合、ポイント(x0, y0)、(x1, y1)、(x2, y2)がすべて1つの直線上にある場合、ポイント(x1, y1)をサブパスに追加し、そのポイントを前のポイント(x0, y0)と直線で接続します。
それ以外の場合、The Arcを円の周囲に沿った最も短い弧とし、radiusを持ち、ポイント(x0, y0)を通過する半無限直線に接するポイントを1つ持ち、ポイント(x1, y1)を通過する別の半無限直線に接するポイントを持つ円として定義します。この円がこれらの2つの直線に接するポイントは、それぞれ開始接点および終了接点と呼ばれます。ポイント(x0, y0)を開始接点に直線で接続し、開始接点をサブパスに追加し、その後、開始接点をThe Arcで終了接点に接続し、終了接点をサブパスに追加します。
arc(x, y, radius, startAngle, endAngle, counterclockwise)メソッドが呼び出されたとき、楕円メソッドの手順をこのオブジェクトに対して実行する必要があります。x, y,
radius, radius, 0, startAngle, endAngle,
およびcounterclockwiseを渡して。
これにより、両方の半径が等しく、rotationが0である点を除いて、ellipse()と同等になります。
ellipse(x, y, radiusX, radiusY, rotation, startAngle, endAngle, counterclockwise)メソッドが呼び出されたとき、楕円メソッドの手順をこのオブジェクトに対して実行する必要があります。x, y,
radiusX, radiusY, rotation, startAngle, endAngle,
およびcounterclockwiseを渡して。
楕円上のポイントを決定する手順は、与えられたellipseとangleに基づいて以下の手順で実行します:
eccentricCircleを、ellipseと原点を共有し、ellipseの半長軸と等しい半径を持つ円とします。
outerPointを、ellipseの半長軸から時計回りに測定したangleの位置にあるeccentricCircleの周囲のポイントとします。
chordを、ellipseの長軸に垂直なラインで、長軸とouterPointの間のラインとします。
chordがellipseの周囲を横切るポイントを返します。
楕円メソッドの手順は、与えられたcanvasPath, x, y, radiusX, radiusY, rotation, startAngle, endAngle, およびcounterclockwiseに基づいて以下の手順で実行します:
引数のいずれかが無限大またはNaNである場合は、終了します。
radiusXまたはradiusYのいずれかが負の場合、"IndexSizeError"DOMExceptionをスローします。
canvasPathのパスにサブパスがある場合、最後のポイントから弧の開始ポイントまで直線を追加します。
弧の開始点と終了点をサブパスに追加し、それらを弧で接続します。弧およびその開始点と終了点は次のように定義されます:
(x, y)に原点を持ち、半長軸の半径がradiusX、半短軸の半径がradiusYである楕円を考え、この楕円はその原点を中心にして回転し、その半長軸がx軸からrotationラジアン時計回りに傾いているとします。
counterclockwiseがfalseであり、endAngle − startAngleが2π以上の場合、またはcounterclockwiseがtrueであり、startAngle − endAngleが2π以上の場合、弧はこの楕円の全周であり、開始点および終了点は、この楕円とstartAngleで与えられた角度に基づいて楕円上のポイントを決定する手順を実行した結果です。
そうでない場合、開始点はこの楕円とstartAngleに基づいて楕円上のポイントを決定する手順を実行した結果であり、終了点はこの楕円とendAngleに基づいて楕円上のポイントを決定する手順を実行した結果です。弧は開始点から終了点までの楕円の周囲のパスであり、counterclockwiseがtrueの場合は反時計回りに、そうでない場合は時計回りに移動します。ポイントが楕円上にあるため、角度は2πラジアンを超えることはありません。
弧が楕円の全周をカバーし、サブパスに他のポイントがない場合でも、closePath()メソッドが適切に呼び出されない限り、パスは閉じられません。
rect(x,
y, w, h) メソッドが呼び出されたとき、以下の手順を実行します:
引数のいずれかが無限大またはNaNである場合、終了します。
指定されたポイント (x, y), (x+w, y), (x+w, y+h), (x, y+h) を順に含む新しいサブパスを作成し、これらの4つのポイントを直線で接続します。
サブパスを閉じたものとしてマークします。
ポイント (x, y) を唯一のポイントとしてサブパスを新規作成します。
CanvasRenderingContext2D/roundRect
すべての最新エンジンでサポートされています。
roundRect(x, y, w,
h, radii) メソッドの手順は以下の通りです:
x, y, w, または h が無限大またはNaNである場合、終了します。
radii が unrestricted
double または DOMPointInit
の場合、radii を « radii » に設定します。
radii がサイズ1、2、3、4のリストでない場合、RangeError
をスローします。
normalizedRadii を空のリストとして設定します。
radii の各 radius に対して:
radius が DOMPointInit
の場合:
radius["x"] または
radius["y"]
が負の場合、RangeError
をスローします。
それ以外の場合、radius を normalizedRadii に追加します。
radius が unrestricted double
の場合:
radius が無限大またはNaNである場合、終了します。
radius が負の場合、RangeError
をスローします。
それ以外の場合、«[ "x" →
radius, "y" →
radius ]» を normalizedRadii に追加します。
upperLeft, upperRight, lowerRight, lowerLeft をnullに設定します。
normalizedRadii のサイズが4の場合、upperLeft を normalizedRadii[0] に設定し、upperRight を normalizedRadii[1] に設定し、lowerRight を normalizedRadii[2] に設定し、lowerLeft を normalizedRadii[3] に設定します。
normalizedRadii のサイズが3の場合、upperLeft を normalizedRadii[0] に設定し、upperRight と lowerLeft を normalizedRadii[1] に設定し、lowerRight を normalizedRadii[2] に設定します。
normalizedRadii のサイズが2の場合、upperLeft と lowerRight を normalizedRadii[0] に設定し、upperRight と lowerLeft を normalizedRadii[1] に設定します。
normalizedRadii のサイズが1の場合、upperLeft, upperRight, lowerRight, lowerLeft を normalizedRadii[0] に設定します。
角のカーブが重ならないようにするために、すべての半径を縮小します:
新しいサブパスを作成します:
ポイント (x + upperLeft["x"], y)
に移動します。
ポイント (x + w − upperRight["x"], y)
まで直線を引きます。
ポイント (x + w, y + upperRight["y"]) に弧を描きます。
ポイント (x + w, y + h − lowerRight["y"]) まで直線を引きます。
ポイント (x + w − lowerRight["x"], y +
h) に弧を描きます。
ポイント (x + lowerLeft["x"], y +
h) まで直線を引きます。
ポイント (x, y + h − lowerLeft["y"]) に弧を描きます。
ポイント (x, y + upperLeft["y"]) まで直線を引きます。
ポイント (x + upperLeft["x"], y)
に弧を描きます。
サブパスを閉じたものとしてマークします。
ポイント (x, y) を唯一のポイントとしてサブパスを新規作成します。
これは、CSSの'border-radius'プロパティと同様に機能するように設計されています。
Path2D オブジェクトすべての現在のエンジンでサポートされています。
Path2D オブジェクトは、次に使用されるパスを宣言するために使用されます。
オブジェクトを実装します。CanvasDrawPathインターフェースを実装するオブジェクトです。
先に説明された多くのAPIに加えて、Path2D
オブジェクトには、パスを結合したり、パスにテキストを追加したりするためのメソッドがあります。
path = new Path2D()
すべての現在のエンジンでサポートされています。
新しい空のPath2Dオブジェクトを作成します。
path = new Path2D(path)
pathがPath2D
オブジェクトの場合、
コピーを返します。
pathが文字列の場合、引数で指定されたパスを作成し、SVGパスデータとして解釈します。[SVG]
path.addPath(path [, transform ])
すべての現在のエンジンでサポートされています。
引数で与えられたパスをパスに追加します。
Path2D(path)
コンストラクターが呼び出されたとき、これらの手順を実行する必要があります:
outputを新しいPath2D
オブジェクトに設定します。
pathが指定されていない場合、outputを返します。
pathがPath2D
オブジェクトの場合、
pathのすべてのサブパスをoutputに追加し、outputを返します。(つまり、引数のコピーを返します。)
svgPathを、pathを解析して解釈した結果に設定します。SVG 2のパスデータに関する規則に従います。[SVG]
結果のパスは空である可能性があります。SVGはパスデータの解析と適用に関するエラーハンドリングルールを定義しています。
svgPathの最後のポイントをx、yに設定します。
存在する場合、svgPathのすべてのサブパスをoutputに追加します。
outputに新しいサブパスを作成し、(x, y)をサブパスの唯一のポイントとして設定します。
outputを返します。
addPath(path,
transform) メソッドは、Path2D オブジェクト
aに対して呼び出された場合、次の手順を実行する必要があります:
Path2D オブジェクト path
にサブパスがない場合、返します。
matrixを、2D辞書からDOMMatrix
を作成するの結果に設定します。
transform。
1つ以上のmatrixの要素が無限大またはNaNである場合、返します。
path内のすべてのサブパスのコピーを作成します。このコピーをcと呼びます。
c内のすべての座標と線を、変換行列matrixで変換します。
cの最後のサブパスの最後のポイントを(x, y)に設定します。
c内のすべてのサブパスをaに追加します。
aに新しいサブパスを作成し、(x, y)をサブパスの唯一のポイントとして設定します。
CanvasTransformインターフェースを実装するオブジェクトには、現在の変換行列があり、それを操作するためのメソッド(このセクションで説明)が備わっています。CanvasTransformインターフェースを実装するオブジェクトが作成されると、その変換行列は単位行列に初期化される必要があります。
現在の変換行列は、現在のデフォルトパスを作成するときや、テキスト、形状、およびPath2Dオブジェクトを描画するときに適用されます。これらのオブジェクトは、CanvasTransformインターフェースを実装します。
変換は逆順に実行する必要があります。
例えば、キャンバスに幅を2倍にするスケーリング変換を適用し、その後に描画操作を四分の一回転させる回転変換を適用し、最後に幅が高さの2倍の長方形をキャンバスに描画した場合、実際の結果は正方形になります。
context.scale(x, y)
CanvasRenderingContext2D/scale
すべての現在のエンジンでサポートされています。
現在の変換行列を変更して、指定された特性を持つスケーリング変換を適用します。
context.rotate(angle)
CanvasRenderingContext2D/rotate
すべての現在のエンジンでサポートされています。
現在の変換行列を変更して、指定された特性を持つ回転変換を適用します。角度はラジアンで指定されます。
context.translate(x, y)
CanvasRenderingContext2D/translate
すべての現在のエンジンでサポートされています。
現在の変換行列を変更して、指定された特性を持つ平行移動変換を適用します。
context.transform(a, b, c, d, e, f)
CanvasRenderingContext2D/transform
すべての現在のエンジンでサポートされています。
現在の変換行列を変更して、以下に説明するように引数で指定された行列を適用します。
matrix = context.getTransform()
CanvasRenderingContext2D/getTransform
すべての現在のエンジンでサポートされています。
context.setTransform(a, b, c, d, e, f)
CanvasRenderingContext2D/setTransform
すべての現在のエンジンでサポートされています。
現在の変換行列を以下に説明するように、引数で指定された行列に設定します。
context.setTransform(transform)
現在の変換行列を、指定されたDOMMatrix2DInit辞書が表す行列に設定します。
context.resetTransform()
CanvasRenderingContext2D/resetTransform
すべての現在のエンジンでサポートされています。
現在の変換行列を単位行列にリセットします。
scale(x, y)メソッドが呼び出されると、次の手順が実行されます:
引数のいずれかが無限大またはNaNの場合、戻ります。
引数で指定されたスケーリング変換を現在の変換行列に追加します。x引数は水平方向のスケールファクターを表し、y引数は垂直方向のスケールファクターを表します。これらのファクターは倍数です。
rotate(angle)メソッドが呼び出されると、次の手順が実行されます:
angleが無限大またはNaNの場合、戻ります。
引数で指定された回転変換を現在の変換行列に追加します。angle引数は時計回りの回転角をラジアンで表します。
translate(x, y)メソッドが呼び出されると、次の手順が実行されます:
引数のいずれかが無限大またはNaNの場合、戻ります。
引数で指定された平行移動変換を現在の変換行列に追加します。x引数は水平方向の移動距離を表し、y引数は垂直方向の移動距離を表します。これらの引数は座標空間の単位で指定されます。
transform(a, b, c, d, e, f)メソッドが呼び出されると、次の手順が実行されます:
引数a、b、c、d、e、およびfは、時にはm11、m12、m21、m22、dx、およびdyと呼ばれることがあります。また、m12/m21やm21/m12などの表記がAPIによって異なることがあるため、特にbとcの順番には注意が必要です。
getTransform()メソッドが呼び出されると、コンテキストの現在の変換行列のコピーを表す新しく作成されたDOMMatrixを返します。
返されたオブジェクトはライブではないため、それを更新しても現在の変換行列には影響しませんし、現在の変換行列を更新しても、すでに返されたDOMMatrixには影響しません。
setTransform(a, b, c, d, e, f)メソッドが呼び出されると、次の手順が実行されます:
引数のいずれかが無限大またはNaNの場合、戻ります。
現在の変換行列を次の行列にリセットします:
| a | c | e |
| b | d | f |
| 0 | 0 | 1 |
setTransform(transform)メソッドが呼び出されると、次の手順が実行されます:
2D辞書からDOMMatrixを作成する結果として、transformからmatrixを作成します。
matrixのm11要素、m12要素、m21要素、m22要素、m41要素、またはm42要素のいずれかが無限大またはNaNの場合、戻ります。
現在の変換行列をmatrixにリセットします。
resetTransform()メソッドが呼び出されると、現在の変換行列を単位行列にリセットします。
transform()およびsetTransform()メソッドで作成された形式の行列が与えられた場合、
| a | c | e |
| b | d | f |
| 0 | 0 | 1 |
変換行列の掛け算後の変換された座標は次のようになります:
xnew = a x + c y + e
ynew = b x + d y + f
一部のメソッドでは、CanvasDrawImage
および CanvasFillStrokeStyles
インターフェイスが共用体型CanvasImageSource
を引数として取ります。
この共用体型は、以下のインターフェイスを実装するオブジェクトを画像ソースとして使用することを可能にします:
HTMLOrSVGImageElement
(img
または SVG
image 要素)HTMLVideoElement
(video
要素)HTMLCanvasElement
(canvas
要素)OffscreenCanvas
ImageBitmap
VideoFrame
正式には指定されていませんが、SVG
image 要素は img
要素とほぼ同じように実装されると予想されます。つまり、SVG
image 要素は img
要素の基本的な概念と機能を共有しています。
ImageBitmap
インターフェイスは、ImageData
などの他の画像表現型から作成することができます。
画像引数の使用可能性を確認するには、image が CanvasImageSource
オブジェクトである場合、次の手順を実行します:
image の種類に応じて以下を切り替えます:
HTMLOrSVGImageElement
もし image の 現在のリクエスト の 状態 が 壊れている ならば、"InvalidStateError" DOMException
を投げます。
もし image が 完全にデコード可能 でない場合、悪い を返します。
HTMLVideoElement
もし image の readyState
属性が HAVE_NOTHING
または HAVE_METADATA
のいずれかである場合、悪い を返します。
HTMLCanvasElement
OffscreenCanvas
もし image が水平方向または垂直方向のいずれかの寸法がゼロである場合、"InvalidStateError" DOMException
を投げます。
ImageBitmap
VideoFrame
もし image の [[Detached]]
内部スロット値がtrueに設定されている場合、"InvalidStateError" DOMException
を投げます。
良い を返します。
ある CanvasImageSource
オブジェクトが HTMLOrSVGImageElement
を表す場合、要素の画像をソース画像として使用しなければなりません。
具体的には、CanvasImageSource
オブジェクトがアニメーション画像を表す場合、ユーザーエージェントは、アニメーションがサポートされていない、または無効化されている場合に使用するようにフォーマットで定義されているデフォルト画像を使用する必要があります。そうでない場合、アニメーションの最初のフレームを使用して、CanvasRenderingContext2D
APIで画像をレンダリングします。
ある CanvasImageSource
オブジェクトが HTMLVideoElement
を表す場合、メソッドが呼び出されたときの 現在の再生位置
でのフレームをソース画像として使用し、ソース画像の寸法は、自然な幅 および 自然な高さ でなければなりません。
ある CanvasImageSource
オブジェクトが HTMLCanvasElement
を表す場合、要素のビットマップをソース画像として使用しなければなりません。
ある CanvasImageSource
オブジェクトが描画中の要素を表し、その要素がリサイズされている場合、ソース画像の元の画像データを使用しなければなりません。レンダリングされた画像ではなく (例:ソース要素の 幅 および 高さ
属性は、CanvasRenderingContext2D
APIで画像をレンダリングする際に、オブジェクトの解釈に影響を与えません)。
ある CanvasImageSource
オブジェクトが ImageBitmap
を表す場合、そのオブジェクトのビットマップ画像データをソース画像として使用しなければなりません。
ある CanvasImageSource
オブジェクトが OffscreenCanvas
を表す場合、そのオブジェクトのビットマップをソース画像として使用しなければなりません。
ある CanvasImageSource
オブジェクトが VideoFrame
を表す場合、そのオブジェクトのピクセルデータをソース画像として使用し、ソース画像の寸法はオブジェクトの [[表示幅]] および [[表示高さ]] でなければなりません。
image というオブジェクトがオリジンがクリーンでない場合、image の種類に応じて:
HTMLOrSVGImageElement
image の 現在のリクエスト の 画像データ が CORS-クロスオリジン である。
HTMLVideoElement
image の メディアデータ が CORS-クロスオリジン である。
HTMLCanvasElement
ImageBitmap
OffscreenCanvas
image のビットマップの オリジンがクリーンである フラグが false である。
context.fillStyle [ = value ]
CanvasRenderingContext2D/fillStyle
すべての現在のエンジンでサポートされています。
現在の塗りつぶしに使用されるスタイルを返します。
設定可能で、塗りつぶしスタイルを変更できます。
スタイルは、CSS カラーを含む文字列、CanvasGradient、または
CanvasPattern
オブジェクトのいずれかです。
無効な値は無視されます。
context.strokeStyle [ = value ]
CanvasRenderingContext2D/strokeStyle
すべての現在のエンジンでサポートされています。
現在の描画に使用されるスタイルを返します。
設定可能で、ストロークスタイルを変更できます。
スタイルは、CSS カラーを含む文字列、CanvasGradient、または
CanvasPattern
オブジェクトのいずれかです。
無効な値は無視されます。
CanvasFillStrokeStyles
インターフェイスを実装するオブジェクトには、そのオブジェクトが図形をどのように処理するかを制御する属性とメソッドが定義されています。
このようなオブジェクトには、塗りつぶしスタイル と ストロークスタイル の値が関連付けられています。これらの値は、CSS カラー、CanvasPattern または CanvasGradient
のいずれかです。最初は、どちらも 文字列
"#000000" の解析 の結果でなければなりません。
値が CSS カラーの場合、ビットマップに描画する際に変換行列の影響を受けてはなりません。
CanvasPattern または
CanvasGradient
オブジェクトに設定されると、割り当て後に行われた変更は、その後の図形の描画や塗りつぶしに影響します。
fillStyle のゲッターステップは次のとおりです。
fillStyle
のセッターステップは次のとおりです。
指定された値が文字列である場合:
指定された値が CanvasPattern
オブジェクトで、オリジンクリーンではない とマークされている場合、this の オリジンクリーン フラグを false に設定します。
strokeStyle のゲッターステップは次のとおりです。
strokeStyle
のセッターステップは次のとおりです。
指定された値が文字列である場合:
指定された値が CanvasPattern
オブジェクトで、オリジンクリーンではない とマークされている場合、this の オリジンクリーン フラグを false に設定します。
カラーのシリアル化 は、次のように計算される文字列です。アルファが 1.0 の場合、文字列は "#" 文字 (U+0023 NUMBER SIGN)
で始まる小文字の 6 桁の 16 進数で、最初の 2 桁が赤の成分、次の 2 桁が緑の成分、最後の 2 桁が青の成分を表します。この桁は、ASCII 小文字の
16 進数桁 です。 それ以外の場合、カラー値のアルファは 1.0 未満であり、文字列は CSS の rgba() 関数表記形式 "rgba"
(U+0072 U+0067 U+0062 U+0061) に続いて U+0028 左括弧、赤の成分を表す範囲 0-255 の 10 進整数 (ASCII 桁 を使用) で、リテラル U+002C コンマと U+0020
スペース、緑の成分の整数、コンマとスペース、青の成分の整数、もう一つのコンマとスペース、U+0030 数字のゼロ、アルファ値が 0 より大きい場合は U+002E ピリオド (小数点を表す)、アルファ値が 0
より大きい場合は小数部を表す 1 つ以上の ASCII 桁 が続き、最後に U+0029
右括弧が続きます。ユーザーエージェントは、アルファ値の小数部がある場合、アルファ値が再解析される際に同じアルファ値として解釈されるのに必要な精度のレベルで小数部を表現する必要があります。
グラデーションには、線形グラデーション、放射状グラデーション、および円錐グラデーションの3種類があり、これらは不透明なCanvasGradientインターフェースを実装するオブジェクトによって表されます。
一度グラデーションが作成されると(以下参照)、ストップがその上に配置され、グラデーションに沿った色の分布が定義されます。各ストップでのグラデーションの色は、そのストップに指定された色です。各ストップの間では、アルファ値を事前に乗算せずに、RGBA空間で線形補間を行い、そのオフセットで使用する色を見つける必要があります。最初のストップの前では、色は最初のストップの色でなければなりません。最後のストップの後では、色は最後のストップの色でなければなりません。ストップがない場合、グラデーションは透明な黒になります。
gradient.addColorStop(offset, color)
すべての現在のエンジンでサポートされています。
指定されたオフセットで、指定された色を持つカラーストップをグラデーションに追加します。0.0 はグラデーションの片端のオフセットであり、1.0 はもう一方のオフセットです。
オフセットが範囲外の場合、"IndexSizeError" DOMExceptionをスローします。色が解析できない場合は、"SyntaxError" DOMExceptionをスローします。
gradient = context.createLinearGradient(x0, y0, x1, y1)
CanvasRenderingContext2D/createLinearGradient
すべての現在のエンジンでサポートされています。
引数で表される座標によって与えられる線に沿って描画する線形グラデーションを表すCanvasGradientオブジェクトを返します。
gradient = context.createRadialGradient(x0, y0, r0, x1, y1, r1)
CanvasRenderingContext2D/createRadialGradient
すべての現在のエンジンでサポートされています。
引数で表される円によって与えられる円錐に沿って描画する放射状グラデーションを表すCanvasGradientオブジェクトを返します。
半径のいずれかが負の場合、"IndexSizeError" DOMException例外をスローします。
gradient = context.createConicGradient(startAngle, x, y)
CanvasRenderingContext2D/createConicGradient
すべての現在のエンジンでサポートされています。
引数で表される中心の周りの回転に沿って時計回りに描画する円錐グラデーションを表すCanvasGradientオブジェクトを返します。
CanvasGradientのaddColorStop(offset, color)メソッドは、呼び出されたときに、次のステップを実行する必要があります:
offsetが0より小さいか、または1より大きい場合は、"IndexSizeError" DOMExceptionをスローします。
parsed colorをcolorの解析の結果として設定します。
要素はパーサーに渡されません。これはCanvasGradientオブジェクトがcanvasに依存しないためです。あるCanvasGradientオブジェクトは別のcanvasによって使用される可能性があるため、色が指定された時点で「問題の要素」を知る方法がないのです。
parsed colorが失敗した場合、"SyntaxError" DOMExceptionをスローします。
グラデーション全体に対してoffsetの位置に、新しいストップを追加し、その色をparsed colorとします。
同じオフセットに複数のストップが追加された場合、それらは追加された順序で配置される必要があり、最初のストップがグラデーションの開始に最も近く、次のストップが最初のストップに非常に近い位置に配置され、最初と最後のストップ以外は無視されることになります。
createLinearGradient(x0, y0, x1, y1)メソッドは、グラデーションの開始点(x0,
y0)と終了点(x1, y1)を表す4つの引数を受け取ります。メソッドが呼び出されると、指定された線で初期化された線形CanvasGradientを返す必要があります。
線形グラデーションは、開始点と終了点を横切る線に垂直なすべての点が、これら2つの線が交差する点での色を持つように描画される必要があります(色は上記で説明した補間および外挿から取得されます)。線形グラデーションの点は、描画時に現在の変換行列によって説明されるように変換される必要があります。
x0 = x1かつy0 = y1の場合、線形グラデーションは何も描画してはなりません。
createRadialGradient(x0, y0, r0, x1, y1, r1)メソッドは6つの引数を受け取り、最初の3つは開始円の原点(x0,
y0)および半径r0を表し、最後の3つは終了円の原点(x1,
y1)および半径r1を表します。値は座標空間の単位です。r0またはr1のいずれかが負の場合、"IndexSizeError" DOMExceptionをスローする必要があります。それ以外の場合、このメソッドが呼び出されると、指定された2つの円で初期化された放射CanvasGradientを返す必要があります。
放射状グラデーションは次の手順に従って描画する必要があります:
x0 = x1かつy0 = y1かつr0 = r1の場合、放射状グラデーションは何も描画してはなりません。終了します。
x(ω) = (x1-x0)ω + x0とします。
y(ω) = (y1-y0)ω + y0とします。
r(ω) = (r1-r0)ω + r0とします。
ωでの色を、その位置でのグラデーションの色とします(色は上記で説明した補間および外挿から取得されます)。
r(ω) > 0であるすべてのωの値について、正の無限大に最も近いωの値から始めて、負の無限大に最も近いωの値で終了し、半径r(ω)を持つ円の円周を、位置(x(ω), y(ω))に描画します。ただし、このグラデーションのレンダリングのこのステップで前に描画された円によってまだ描画されていないビットマップの部分だけを塗りつぶします。
これは事実上、グラデーションの作成時に定義された2つの円によって接触される円錐を作成し、開始円(0.0)の前の部分は最初のオフセットの色を使用し、終了円(1.0)の後の部分は最後のオフセットの色を使用し、グラデーションによって触れられていない領域は透明な黒になります。
その後、得られた放射状グラデーションは、描画時に現在の変換行列によって説明されるように変換される必要があります。
createConicGradient(startAngle, x, y)メソッドは3つの引数を受け取り、最初の引数であるstartAngleはグラデーションが始まる角度(ラジアン単位)を表し、最後の2つの引数(x,
y)はCSSピクセルでのグラデーションの中心を表します。メソッドが呼び出されると、指定された中心と角度で初期化された円錐のCanvasGradientを返す必要があります。
これはCSS'conic-gradient'と同じ描画ルールに従い、CSS 'conic-gradient(from adjustedStartAnglerad at xpx ypx, angularColorStopList)'と等価です。ここでは:
adjustedStartAngleはstartAngle + π/2で与えられます。
angularColorStopListはCanvasGradientにaddColorStop()を使用して追加されたカラーストップによって与えられ、カラーストップのオフセットはパーセンテージとして解釈されます。
グラデーションは、関連するストロークまたは塗りつぶしの効果がそれらを描画する必要がある場合にのみ描画される必要があります。
パターンは、透明なCanvasPatternインターフェースを実装するオブジェクトによって表されます。
pattern = context.createPattern(image, repetition)
CanvasRenderingContext2D/createPattern
すべての現行エンジンでサポートされています。
指定された画像を使用し、repetition引数で指定された方向に繰り返されるCanvasPatternオブジェクトを返します。
repetitionの許可される値は、repeat(両方向)、repeat-x(水平のみ)、repeat-y(垂直のみ)、およびno-repeat(どちらでもない)です。repetition引数が空の場合、値repeatが使用されます。
画像がまだ完全にデコードされていない場合、何も描画されません。画像がデータのないキャンバスである場合、"InvalidStateError" DOMExceptionがスローされます。
pattern.setTransform(transform)
すべての現行エンジンでサポートされています。
塗りつぶしまたはストロークの描画操作中にパターンをレンダリングする際に使用される変換行列を設定します。
createPattern(image, repetition)メソッドは、呼び出されたときに、次のステップを実行する必要があります:
usabilityを、imageの使用可能性を確認する結果として設定します。
usabilityが悪い場合、nullを返します。
アサート: usabilityが良いことを確認します。
repetitionが空文字列である場合、"repeat"に設定します。
repetitionが"repeat", "repeat-x", "repeat-y",
"no-repeat"のいずれかと一致しない場合、"SyntaxError" DOMExceptionをスローします。
imageとrepetitionによって指定された繰り返し動作を持つ新しいCanvasPatternオブジェクトをpatternとして設定します。
imageがオリジンを保持していない場合、patternをオリジンを保持していないとしてマークします。
patternを返します。
createPattern()メソッドを呼び出した後、CanvasPatternオブジェクトでレンダリングされたパターンに使用されるimageを変更しても、描画されるパターンに影響を与えてはいけません。
パターンには変換行列があり、パターンが描画される際の使用方法を制御します。初期状態では、パターンの変換行列は単位行列でなければなりません。
setTransform(transform)メソッドは、呼び出されたときに、次のステップを実行する必要があります:
transformを使用して、2D辞書からDOMMatrixを作成する結果をmatrixとして設定します。
matrixのm11要素、m12要素、m21要素、m22要素、m41要素、またはm42要素の1つ以上が無限大またはNaNである場合は、何も返さず終了します。
パターンの変換行列をmatrixにリセットします。
パターンを領域内にレンダリングする場合、ユーザーエージェントは次の手順を実行してレンダリングされる内容を決定する必要があります:
無限の透明な黒ビットマップを作成します。
画像の左上隅が座標空間の原点に位置するようにビットマップに画像のコピーを配置し、画像の1つのCSSピクセルあたり1つの座標空間単位で、repeat-xの場合は左右に、repeat-yの場合は上下に、repeatの場合はビットマップ全体に画像の繰り返しコピーを配置します。
元の画像データがビットマップ画像である場合、繰り返し領域内のポイントに描画される値は、元の画像データをフィルタリングすることで計算されます。拡大する場合、imageSmoothingEnabled属性がfalseに設定されている場合、画像は最近傍補間を使用してレンダリングされる必要があります。それ以外の場合、ユーザーエージェントは任意のフィルタリングアルゴリズム(たとえば、バイリニア補間や最近傍補間など)を使用できます。複数のフィルタリングアルゴリズムをサポートするユーザーエージェントは、imageSmoothingQuality属性の値を使用してフィルタリングアルゴリズムの選択をガイドすることができます。このようなフィルタリングアルゴリズムが元の画像データの外からピクセル値を必要とする場合、代わりにピクセルの座標を元の画像の寸法にラップして使用する必要があります。(つまり、パターンの繰り返し動作の値に関係なく、フィルタは「repeat」動作を使用します。)
結果のビットマップをパターンの変換行列に従って変換します。
次に、現在の変換行列に従って再度結果のビットマップを変換します。
パターンが描画される領域の外部にある画像の部分を透明な黒に置き換えます。
結果のビットマップが、同じ原点と同じスケールで描画されるものになります。
変換行列が特異な場合に放射状グラデーションや繰り返しパターンが使用されると、結果のスタイルは透明な黒でなければなりません(そうでなければ、グラデーションやパターンが一点や線に縮小され、他のピクセルが未定義のままになる可能性があります)。線形グラデーションや単色は、特異な変換行列でも常にすべてのポイントを定義します。
CanvasRectインターフェースを実装するオブジェクトは、ビットマップに即座に長方形を描画するための次のメソッドを提供します。これらのメソッドはそれぞれ4つの引数を取り、最初の2つは長方形の左上のxおよびy座標を、残りの2つはそれぞれ長方形の幅wと高さhを指定します。
次に示す4つの座標に適用された現在の変換行列を使用してパスを形成し、その後閉じて指定された長方形を得る必要があります: (x, y), (x+w, y), (x+w, y+h), (x, y+h)。
シェイプは現在のデフォルトパスに影響を与えずに描画され、クリッピング領域の影響を受けます。また、clearRect()を除き、シャドウ効果、グローバルアルファ、および現在の合成およびブレンディングオペレーターの影響も受けます。
context.clearRect(x, y, w, h)
CanvasRenderingContext2D/clearRect
すべての現行エンジンでサポートされています。
指定された長方形内のビットマップ上のすべてのピクセルを透明な黒にクリアします。
context.fillRect(x, y, w, h)
CanvasRenderingContext2D/fillRect
すべての現行エンジンでサポートされています。
現在の塗りつぶしスタイルを使用して、ビットマップに指定された長方形を描画します。
context.strokeRect(x, y, w, h)
CanvasRenderingContext2D/strokeRect
すべての現行エンジンでサポートされています。
現在のストロークスタイルを使用して、指定された長方形をビットマップにアウトラインとして描画します。
clearRect(x, y, w,
h)メソッドは、呼び出されたとき、次のステップを実行する必要があります。
引数のいずれかが無限大またはNaNである場合は、何もせずに戻ります。
pixelsを、指定された長方形内で、現在のクリッピング領域と交差するピクセルのセットとして設定します。
pixels内のピクセルを透明な黒にクリアし、以前の画像を消去します。
高さまたは幅のいずれかがゼロの場合、このメソッドには効果がありません。ピクセルのセットが空になるためです。
fillRect(x, y, w, h)メソッドは、呼び出されたとき、次のステップを実行する必要があります。
引数のいずれかが無限大またはNaNである場合は、何もせずに戻ります。
wまたはhのいずれかがゼロである場合は、何もせずに戻ります。
strokeRect(x, y, w, h)メソッドは、呼び出されたとき、次のステップを実行する必要があります。
引数のいずれかが無限大またはNaNである場合は、何もせずに戻ります。
以下に説明するパスをトレースする結果を取得し、CanvasPathDrawingStylesインターフェースのラインスタイルを使用してそれを描画し、thisのストロークスタイルで塗りつぶします。
もしwとhの両方がゼロの場合、パスは(x, y)の1点だけを持つ単一のサブパスとなり、このメソッドには効果がありません(この場合、パスをトレースするアルゴリズムは空のパスを返します)。
もしwまたはhのいずれかがゼロの場合、パスは(x, y)と(x+w, y+h)の2点からなる単一のサブパスとなり、それらは直線で結ばれます。
それ以外の場合、パスは4つの点からなる単一のサブパスを持ち、その点は順に(x, y), (x+w, y), (x+w, y+h), および(x, y+h)で、それらは順に直線で結ばれます。
すべての現在のエンジンでサポートされています。
context.fillText(text, x, y [, maxWidth ])
CanvasRenderingContext2D/fillText
すべての現在のエンジンでサポートされています。
context.strokeText(text, x, y [, maxWidth ])
CanvasRenderingContext2D/strokeText
すべての現在のエンジンでサポートされています。
指定された位置にテキストを描画または描きます。最大幅が指定されている場合、テキストはその幅に合わせてスケーリングされます。
metrics = context.measureText(text)
CanvasRenderingContext2D/measureText
すべての現在のエンジンでサポートされています。
TextMetrics
オブジェクトを返し、現在のフォントでの指定されたテキストのメトリック情報を提供します。
metrics.width
すべての現在のエンジンでサポートされています。
metrics.actualBoundingBoxLeft
TextMetrics/actualBoundingBoxLeft
すべての現在のエンジンでサポートされています。
metrics.actualBoundingBoxRight
TextMetrics/actualBoundingBoxRight
すべての現在のエンジンでサポートされています。
metrics.fontBoundingBoxAscent
TextMetrics/fontBoundingBoxAscent
すべての現在のエンジンでサポートされています。
metrics.fontBoundingBoxDescent
TextMetrics/fontBoundingBoxDescent
すべての現在のエンジンでサポートされています。
metrics.actualBoundingBoxAscent
TextMetrics/actualBoundingBoxAscent
すべての現在のエンジンでサポートされています。
metrics.actualBoundingBoxDescent
TextMetrics/actualBoundingBoxDescent
すべての現在のエンジンでサポートされています。
metrics.emHeightAscent
すべての現在のエンジンでサポートされています。
metrics.emHeightDescent
すべての現在のエンジンでサポートされています。
metrics.hangingBaseline
metrics.alphabeticBaseline
TextMetrics/alphabeticBaseline
metrics.ideographicBaseline
TextMetrics/ideographicBaseline
次の測定値を返します。
実装するオブジェクト CanvasText
インターフェイスは、テキストをレンダリングするために次のメソッドを提供します。
fillText(text, x, y, maxWidth)
および strokeText(text, x, y, maxWidth)
メソッドは、指定された (x, y) 座標で text をレンダリングし、指定されている場合は maxWidth
よりも幅が広くならないようにします。これには、現在の font、textAlign、および
textBaseline
の値が使用されます。具体的には、メソッドが呼び出されると、ユーザーエージェントは次のステップを実行しなければなりません:
引数のいずれかが無限大または NaN の場合は、処理を終了します。
テキスト準備アルゴリズム を実行し、text、CanvasText
インターフェイスを実装するオブジェクト、および maxWidth 引数が指定されている場合はその引数を渡します。glyphs を結果とします。
現在の 変換行列 によって変形された glyphs 内の形状を描画します。各 CSS ピクセル は、glyphs の座標空間内で 1 つの座標空間単位にマッピングされます。
fillText()
の場合、this の 塗りつぶしスタイル が形状に適用され、this の ストロークスタイル
は無視されます。strokeText()
の場合はその逆です:this の ストロークスタイル が形状の トレース に適用され、this の 塗りつぶしスタイル は無視されます。
これらの形状は現在のパスに影響を与えずに描画され、シャドウ効果、グローバルアルファ、クリッピング領域、および 現在の合成およびブレンド演算子 の影響を受けます。
measureText(text) メソッドの手順は
テキスト
準備アルゴリズム を実行し、text と
CanvasText
インターフェースを実装するオブジェクトを渡し、その後、返された インライン
ボックス が新しい TextMetrics
オブジェクトを
メンバーとともに返す必要があります。このメンバーは次のリストで説明されているように振る舞います: [CSS]
width
属性
actualBoundingBoxLeft 属性
基準線から textAlign
属性によって指定された整列点までの距離で、テキストのバウンディング
ボックスの左側までの距離を CSS ピクセル で表します; 正の
数値は指定された整列点から左方向の距離を示します。
この値と次の値 (actualBoundingBoxRight)
の合計は インラインボックス
(width)
よりも広くなる可能性があります。特に、スラントフォントでは文字がアドバンス幅を超えてはみ出すことがあります。
actualBoundingBoxRight 属性
基準線から textAlign
属性によって指定された整列点までの距離で、テキストのバウンディング
ボックスの右側までの距離を CSS ピクセル で表します; 正の
数値は指定された整列点から右方向の距離を示します。
fontBoundingBoxAscent 属性
基準線から textBaseline
属性によって示された水平線までの距離で、アセント
メトリック を 最初に利用可能なフォント で表したもので、CSS
ピクセル で表されます; 正の数値は指定された基準線から上方向の距離を示します。
この値と次の値は、描画するテキストが変更されても背景の高さを一貫して保つ必要がある場合に役立ちます。actualBoundingBoxAscent
属性(およびそれに対応する降下の属性)は、特定のテキスト周りのバウンディングボックスを描画する際に役立ちます。
fontBoundingBoxDescent 属性
基準線から textBaseline
属性によって示された水平線までの距離で、降下
メトリック を 最初に利用可能なフォント で表したもので、CSS ピクセル で表されます;
正の数値は指定された基準線から下方向の距離を示します。
actualBoundingBoxAscent 属性
基準線から textBaseline
属性によって示された水平線までの距離で、テキストのバウンディング
ボックスの上部までの距離を CSS ピクセル で表します; 正の
数値は指定された基準線から上方向の距離を示します。
この数値は入力テキストによって大きく変わる可能性があり、最初に指定されたフォントが入力内のすべての文字をカバーしていても変わることがあります。例えば、actualBoundingBoxAscent
の小文字の "o" の場合、アルファベティック基準線 からの距離は大文字の "F" よりも小さいです。値は簡単に負になることがあります;
例えば、em ボックスの上部からの距離 (textBaseline
値 "top")
が単一のコンマ "," のテキストの場合、バウンディングボックスの上部までの距離は負になる可能性が高いです。
actualBoundingBoxDescent 属性
基準線から textBaseline
属性によって示された水平線までの距離で、テキストのバウンディング
ボックスの下部までの距離を CSS ピクセル で表します; 正の
数値は指定された基準線から下方向の距離を示します。
emHeightAscent 属性
基準線から textBaseline
属性によって示された水平線までの距離で、インラインボックス 内の em
スクエアの最も高い上部までの距離を CSS ピクセル で表します; 正の数値は指定された基準線がその
em スクエアの上部より下にあることを示します(したがって、この値は通常正の値になります)。指定された基準線がその em スクエアの上部である場合はゼロ; 指定された基準線がその em
スクエアの中央である場合はフォントサイズの半分です。
emHeightDescent 属性
基準線から textBaseline
属性によって示された水平線までの距離で、インラインボックス 内の em
スクエアの最も低い下部までの距離を CSS ピクセル で表します; 正の数値は指定された基準線がその
em スクエアの下部より上にあることを示します。(指定された基準線がその em スクエアの下部である場合はゼロです。)
hangingBaseline 属性
基準線から textBaseline
属性によって示された水平線までの距離で、ハンギング
基準線 までの距離を CSS ピクセル で表します; 正の数値は指定された基準線がその
ハンギング
基準線 より下にあることを示します。(指定された基準線がその ハンギング
基準線 である場合はゼロです。)
alphabeticBaseline 属性
基準線から textBaseline
属性によって示された水平線までの距離で、アルファベティック
基準線 までの距離を CSS ピクセル で表します; 正の数値は指定された基準線がその
アルファベティック
基準線 より下にあることを示します。(指定された基準線がその アルファベティック基準線 である場合はゼロです。)
ideographicBaseline 属性
基準線から textBaseline
属性によって示された水平線までの距離で、表意的下基準線 までの距離を CSS ピクセル で表します; 正の数値は指定された基準線がその 表意的下基準線 より下にあることを示します。(指定された基準線がその 表意的下基準線 である場合はゼロです。)
fillText()
および
strokeText()
を使用してレンダリングされたグリフは、フォントサイズ(em スクエアサイズ)と measureText()
が返す幅(テキストの幅)によって指定されたボックスからはみ出す可能性があります。この場合、上記で説明したバウンディングボックスの値を使用することが推奨されます。
将来の 2D コンテキスト API のバージョンでは、CSS を使用してレンダリングされたドキュメントの断片を直接キャンバスにレンダリングする方法が提供されるかもしれません。これは、専用のマルチラインレイアウト方法に優先されるでしょう。
CanvasDrawPath
インターフェイスを実装するオブジェクトには、現在のデフォルトパスがあります。描画状態の一部ではありませんが、現在のデフォルトパスは、上記で説明したパスです。
context.beginPath()
CanvasRenderingContext2D/beginPath
全ての最新エンジンでサポートされています。
現在のデフォルトパスをリセットします。
context.fill([ fillRule ])
全ての最新エンジンでサポートされています。
context.fill(path [, fillRule ])
指定されたパスまたは現在のデフォルトパスのサブパスを現在の塗りつぶしスタイルで塗りつぶします。
context.stroke()
CanvasRenderingContext2D/stroke
全ての最新エンジンでサポートされています。
context.stroke(path)
指定されたパスまたは現在のデフォルトパスのサブパスを現在のストロークスタイルで描画します。
context.clip([ fillRule ])
全ての最新エンジンでサポートされています。
context.clip(path [, fillRule ])
指定されたパスまたは現在のデフォルトパスのクリッピング領域をさらに制約し、指定された塗りつぶしルールを使用してパス内の点を決定します。
context.isPointInPath(x, y [, fillRule ])
CanvasRenderingContext2D/isPointInPath
全ての最新エンジンでサポートされています。
context.isPointInPath(path, x, y [, fillRule ])
指定された点が、現在のストロークスタイルを考慮して、現在のデフォルトパスまたは指定されたパスのストロークで覆われた領域にある場合、trueを返します。
beginPath()メソッドのステップは、this の 現在のデフォルトパス のサブパスのリストをクリアして、再びサブパスがゼロになるようにします。
次のメソッド定義で 意図されたパス という用語が Path2Dまたはnullのpathを指す場合、それは
Path2D オブジェクト自体か、そうでなければ 現在のデフォルトパス を意味します。
意図されたパスがPath2Dオブジェクトである場合、そのサブパスの座標と線は、CanvasTransformインターフェイスを実装するオブジェクト上の現在の変換行列に従って変換されます(Path2Dオブジェクト自体には影響を与えません)。意図されたパスが現在のデフォルトパスである場合、それは変換の影響を受けません(これは、変換が構築時にすでに現在のデフォルトパスに影響を与えるため、それが描画されるときに適用すると二重変換が発生するためです)。
fill(fillRule)メソッドのステップは、塗りつぶしのステップをthis、null、およびfillRuleを使用して実行することです。
fill(path, fillRule)メソッドのステップは、塗りつぶしのステップをthis、path、およびfillRuleを使用して実行することです。
塗りつぶしのステップは、CanvasDrawPathcontext、Path2Dまたはnullのpath、および塗りつぶしルールfillRuleを指定して、意図されたパスの全サブパスを、contextの塗りつぶしスタイルを使用して塗りつぶし、fillRuleで指定された塗りつぶしルールを使用して塗りつぶします。開いたサブパスは塗りつぶし時に暗黙的に閉じられる必要があります(実際のサブパスには影響を与えません)。
stroke()メソッドのステップは、ストロークのステップをthisとnullを使用して実行することです。
stroke(path)メソッドのステップは、ストロークのステップをthisとpathを使用して実行することです。
ストロークのステップは、CanvasDrawPathcontextとPath2Dまたはnullのpathを指定して、意図されたパスをpathに対してトレースし、その後、contextのストロークスタイルを使用して塗りつぶし、非ゼロ巻きルールを使用してストロークします。
パスをトレースするアルゴリズムの定義方法の結果として、1回のストローク操作でのパスの重複部分は、その合併が描画されたかのように扱われます。
ストロークのスタイルは、現在のデフォルトパスが使用されている場合でも、描画中に変換の影響を受けます。
パスは、塗りつぶされるかストロークされるとき、現在のデフォルトパスやPath2Dオブジェクトに影響を与えることなく、影の効果、グローバルアルファ、クリッピング領域、および現在の合成およびブレンドオペレーターの対象とされる必要があります。(変換の影響は上記に説明されており、使用するパスに基づいて異なります。)
clip(fillRule)メソッドのステップは、クリップのステップをthis、null、およびfillRuleを使用して実行することです。
clip(path, fillRule)メソッドのステップは、クリップのステップをthis、path、およびfillRuleを使用して実行することです。
クリップのステップは、CanvasDrawPathcontext、Path2Dまたはnullのpath、および塗りつぶしルールfillRuleを指定して、新しいクリッピング領域を作成し、意図されたパスが塗りつぶしルールに従ってパス内の点を決定し、その領域を交差させることで、contextの現在のクリッピング領域とpathのクリッピング領域を作成します。新しいクリッピング領域は、現在のクリッピング領域に置き換わります。
コンテキストが初期化されると、その現在のクリッピング領域は無限大の表面に設定されます(つまり、デフォルトではクリッピングは発生しません)。
isPointInPath(x, y, fillRule)メソッドの手順は、this、null、x、y、fillRuleを与えて、パス内にポイントがあるかを確認する手順の結果を返すことです。
isPointInPath(path, x, y, fillRule)メソッドの手順は、this、path、x、y、fillRuleを与えて、パス内にポイントがあるかを確認する手順の結果を返すことです。
パス内にポイントがあるかを確認する手順では、CanvasDrawPath
context、Path2Dまたはnullのpath、二つの数値xおよびy、および塗りつぶしルール fillRuleを次の手順に従って処理します:
xまたはyが無限大かNaNの場合、falseを返します。
現在の変換に影響されないキャンバス座標空間でのxおよびyの座標が、pathの意図されたパスの内部にある場合(fillRuleで示される塗りつぶしルールに従って判断される)、trueを返します。実際のサブパスに影響を与えずに、開いているサブパスは塗りつぶし時に暗黙的に閉じる必要があります。パス自体の上のポイントは、パスの内部にあるものと見なされます。
falseを返します。
isPointInStroke(x, y)メソッドの手順は、this、null、x、およびyを与えて、ストローク内にポイントがあるかを確認する手順の結果を返すことです。
isPointInStroke(path, x, y)メソッドの手順は、this、path、x、およびyを与えて、ストローク内にポイントがあるかを確認する手順の結果を返すことです。
ストローク内にポイントがあるかを確認する手順では、CanvasDrawPath
context、Path2Dまたはnullのpath、および二つの数値xおよびyを次の手順に従って処理します:
xまたはyが無限大かNaNの場合、falseを返します。
現在の変換に影響されないキャンバス座標空間でのxおよびyの座標が、トレースした pathの意図されたパスから得られるパスの内部にある場合、かつ非ゼロワインディングルールを使用している場合、trueを返します。生成されたパス上のポイントは、パスの内部にあるものと見なされます。
falseを返します。
このキャンバス要素には、いくつかのチェックボックスがあります。パス関連のコマンドが強調表示されています:
< canvas height = 400 width = 750 >
< label >< input type = checkbox id = showA > Show As</ label >
< label >< input type = checkbox id = showB > Show Bs</ label >
<!-- ... -->
</ canvas >
< script >
function drawCheckbox( context, element, x, y, paint) {
context. save();
context. font = '10px sans-serif' ;
context. textAlign = 'left' ;
context. textBaseline = 'middle' ;
var metrics = context. measureText( element. labels[ 0 ]. textContent);
if ( paint) {
context. beginPath();
context. strokeStyle = 'black' ;
context. rect( x- 5 , y- 5 , 10 , 10 );
context. stroke();
if ( element. checked) {
context. fillStyle = 'black' ;
context. fill();
}
context. fillText( element. labels[ 0 ]. textContent, x+ 5 , y);
}
context. beginPath();
context. rect( x- 7 , y- 7 , 12 + metrics. width+ 2 , 14 );
context. drawFocusIfNeeded( element);
context. restore();
}
function drawBase() { /* ... */ }
function drawAs() { /* ... */ }
function drawBs() { /* ... */ }
function redraw() {
var canvas = document. getElementsByTagName( 'canvas' )[ 0 ];
var context = canvas. getContext( '2d' );
context. clearRect( 0 , 0 , canvas. width, canvas. height);
drawCheckbox( context, document. getElementById( 'showA' ), 20 , 40 , true );
drawCheckbox( context, document. getElementById( 'showB' ), 20 , 60 , true );
drawBase();
if ( document. getElementById( 'showA' ). checked)
drawAs();
if ( document. getElementById( 'showB' ). checked)
drawBs();
}
function processClick( event) {
var canvas = document. getElementsByTagName( 'canvas' )[ 0 ];
var context = canvas. getContext( '2d' );
var x = event. clientX;
var y = event. clientY;
var node = event. target;
while ( node) {
x -= node. offsetLeft - node. scrollLeft;
y -= node. offsetTop - node. scrollTop;
node = node. offsetParent;
}
drawCheckbox( context, document. getElementById( 'showA' ), 20 , 40 , false );
if ( context. isPointInPath( x, y) )
document. getElementById( 'showA' ). checked = ! ( document. getElementById( 'showA' ). checked);
drawCheckbox( context, document. getElementById( 'showB' ), 20 , 60 , false );
if ( context. isPointInPath( x, y) )
document. getElementById( 'showB' ). checked = ! ( document. getElementById( 'showB' ). checked);
redraw();
}
document. getElementsByTagName( 'canvas' )[ 0 ]. addEventListener( 'focus' , redraw, true );
document. getElementsByTagName( 'canvas' )[ 0 ]. addEventListener( 'blur' , redraw, true );
document. getElementsByTagName( 'canvas' )[ 0 ]. addEventListener( 'change' , redraw, true );
document. getElementsByTagName( 'canvas' )[ 0 ]. addEventListener( 'click' , processClick, false );
redraw();
</ script >
context.drawFocusIfNeeded(element)
CanvasRenderingContext2D/drawFocusIfNeeded
すべての現在のエンジンでサポートされています。
もしelementがフォーカスされている場合、プラットフォームのフォーカスリングの規約に従って、 現在のデフォルトパスの周りにフォーカスリングを描画します。
context.drawFocusIfNeeded(path, element)
もしelementがフォーカスされている場合、プラットフォームのフォーカスリングの規約に従って pathの周りにフォーカスリングを描画します。
フォーカスリングを描画するために、CanvasUserInterfaceインターフェースを実装するオブジェクトは以下のメソッドを提供します。
drawFocusIfNeeded(element) メソッドのステップは、フォーカスが必要な場合に描画します。
thisを指定して、elementとthisの現在のデフォルトパスを用いて描画します。
drawFocusIfNeeded(path, element) メソッドのステップは、フォーカスが必要な場合に描画します。
this、element、およびpathを指定して描画します。
オブジェクトがCanvasUserInterfaceを実装している場合、
context、要素element、およびパス
pathが指定されている時のフォーカスを描画します。
もしelementがフォーカスされていないか、contextのcanvas要素の子孫ではない場合、何も行いません。
プラットフォームの規約に従って、pathに沿って適切なスタイルのフォーカスリングを描画します。
一部のプラットフォームでは、キーボードからフォーカスされた要素の周りにのみフォーカスリングを描画し、マウスからフォーカスされたものには描画しません。他のプラットフォームでは、関連するアクセシビリティ機能が有効でない限り、いくつかの要素の周りにはフォーカスリングを全く描画しないことがあります。このAPIはこれらの規約に従うことを意図しています。要素がフォーカスされる方法に基づいて区別を実装するユーザーエージェントは、focus()メソッドによってトリガーされたユーザーインタラクションイベントの種類に基づいてフォーカスを分類することが推奨されます。
フォーカスリングは、シャドウ効果、
グローバルアルファ、
現在の合成およびブレンディングオペレータ、
塗りつぶしスタイル、
ストロークスタイル、
またはCanvasPathDrawingStyles、
CanvasTextDrawingStyles
インターフェースのいずれのメンバーも対象とすべきではありませんが、クリッピング領域に従うべきです。(変換の影響は上記に記述されており、使用されるパスによって異なります。)
ユーザーに通知し、意図したパスによって指定された場所にフォーカスがあることを知らせます。ユーザーエージェントは、次にイベントループがレンダリングの更新ステップに達するまで待って、オプションでユーザーに通知することができます。
フォーカスリングを描画する際に、ユーザーエージェントは意図したパス内の開いたサブパスを暗黙的に閉じるべきではありません。
これは、おそらく議論の余地がある点です。たとえば、フォーカスリングが意図したパス内の点の周りに軸に沿った境界ボックスとして描かれる場合、サブパスが閉じているかどうかは影響しません。この仕様では、フォーカスリングがどのように描かれるかを正確に指定していません。ユーザーエージェントは、プラットフォームのネイティブな規約を尊重することが求められます。
このセクションで使用される「ユーザーに通知する」という表現は、永続的な状態の変更を意味するものではありません。たとえば、システムのアクセシビリティAPIを呼び出して、ユーザーの拡大ツールなどの支援技術に通知し、ユーザーの拡大鏡がキャンバスの指定された領域に移動するようにすることを意味する可能性があります。しかし、それはパスを要素に関連付けたり、触覚フィードバック用の領域を提供したりするものではありません。
CanvasDrawImageインターフェースを実装するオブジェクトには、画像を描画するための
drawImage()メソッドがあります。
このメソッドは、3つの異なる引数のセットで呼び出すことができます:
drawImage(image, dx, dy)
drawImage(image, dx, dy, dw, dh)
drawImage(image, sx, sy, sw, sh, dx, dy, dw, dh)
context.drawImage(image, dx, dy)
CanvasRenderingContext2D/drawImage
すべての現在のエンジンでサポートされています。
context.drawImage(image, dx, dy, dw, dh)
context.drawImage(image, sx, sy, sw, sh, dx, dy, dw, dh)
指定された画像をキャンバスに描画します。引数は以下のように解釈されます:

画像がまだ完全にデコードされていない場合、何も描画されません。画像がデータのないキャンバスである場合、"InvalidStateError" DOMExceptionがスローされます。
drawImage()メソッドが呼び出されると、
ユーザーエージェントは以下の手順を実行する必要があります:
引数のいずれかが無限大またはNaNである場合、何も返さない。
usabilityをimage引数の有用性のチェックの結果として定義する。
usabilityが悪い場合、何も描画せずに終了する。
ソースと目的地の矩形を次のように設定します:
dwとdhの引数が指定されていない場合、それらはswとshの値にデフォルト設定されるものとし、 画像の1CSSピクセルが 出力ビットマップの座標空間内の1単位として扱われるように解釈されるものとする。 sx、sy、sw、およびshの引数が省略された場合、それらは0、0、画像の自然な幅 (画像ピクセル単位)、および画像の自然な高さ (画像ピクセル単位)にデフォルト設定されるものとする。 画像に自然な寸法がない場合は、具体的なオブジェクトサイズが代わりに使用され、 それはCSS "具体的なオブジェクトサイズ解決"アルゴリズムを使用して決定されるものとする。 指定されたサイズに明確な幅も高さも、追加の制約もない場合、オブジェクトの自然なプロパティは image引数のものとし、デフォルトのオブジェクトサイズは 出力ビットマップのサイズとする。[CSSIMAGES]
ソース矩形は、4つの点(sx, sy), (sx+sw, sy), (sx+sw, sy+sh), (sx, sy+sh)を持つ矩形です。
目的地の矩形は、4つの点(dx, dy), (dx+dw, dy), (dx+dw, dy+dh), (dx, dy+dh)を持つ矩形です。
ソース矩形がソース画像の外にある場合、ソース矩形はソース画像にクリップされ、目的地矩形も同じ比率でクリップされなければなりません。
目的地の矩形が目的地画像(出力ビットマップ)の外にある場合、目的地矩形の外側に位置するピクセルは破棄されます。これは、目的地が無限キャンバスであり、そのレンダリングが出力ビットマップの寸法にクリップされたかのように扱われます。
swまたはshのいずれかがゼロの場合、何も返さず終了します。何も描画されません。
image引数で指定された領域を、レンダリングコンテキストの出力ビットマップの指定された領域に描画し、 現在の変換行列を目的地矩形に適用します。
画像データは元の方向で処理されなければなりません。たとえ指定された寸法が負であっても。
拡大する際、imageSmoothingEnabled属性がtrueに設定されている場合、
ユーザーエージェントは画像データがスケーリングされる際にスムージングアルゴリズムを適用しようとする必要があります。
複数のフィルタリングアルゴリズムをサポートしているユーザーエージェントは、
imageSmoothingQuality属性の値を使用して
フィルタリングアルゴリズムの選択をガイドすることができます。
それ以外の場合は、画像はニアレストネイバー補間を使用してレンダリングされなければなりません。
この仕様は、画像を縮小するとき、またはimageSmoothingEnabled
属性がtrueに設定されている場合に画像を拡大するときに使用する正確なアルゴリズムを定義していません。
あるcanvas要素が
自分自身に描画される場合、描画モデルは画像が描画される前にソースがコピーされることを要求するため、
canvas要素の一部を
自分自身の重なり合う部分にコピーすることが可能です。
元の画像データがビットマップ画像である場合、目的地矩形のポイントで描画される値は、元の画像データをフィルタリングすることで計算されます。 ユーザーエージェントは任意のフィルタリングアルゴリズム(例えばバイリニア補間やニアレストネイバー)を使用することができます。 フィルタリングアルゴリズムが元の画像データの外部からピクセル値を必要とする場合、 代わりに最も近いエッジピクセルの値を使用しなければなりません。(つまり、フィルタは「エッジにクランプ」動作を使用します。) フィルタリングアルゴリズムがソース矩形の外部だが元の画像データ内にあるピクセル値を必要とする場合、 元の画像データの値が使用されなければなりません。
したがって、画像を部分的にまたは全体的にスケーリングすることは同じ効果を持ちます。
これにより、単一のスプライトシートからスプライトをスケーリングする場合、
スプライトシート内の隣接する画像が干渉する可能性があります。
これを回避するには、シート内の各スプライトが透明な黒の境界で囲まれていることを確認するか、
スケーリングするスプライトを一時的なcanvas要素にコピーし、
そこからスケーリングされたスプライトを描画することで回避できます。
画像は現在のパスに影響を与えることなく描画され、影効果、 グローバルアルファ、 クリッピング領域、 現在の合成およびブレンディングオペレータの影響を受けます。
imageがクリーンなオリジンでない場合、
CanvasRenderingContext2Dのオリジンクリーンフラグをfalseに設定します。
imagedata = new ImageData(sw, sh [, settings])
すべての現在のエンジンでサポートされています。
指定された寸法とsettingsで示される色空間を持つImageDataオブジェクトを返します。返されるオブジェクト内のすべてのピクセルは透明な黒です。
幅または高さのいずれかの引数がゼロの場合、"IndexSizeError" DOMExceptionをスローします。
imagedata = new ImageData(data, sw [, sh [, settings ] ])
提供されたデータを使用して、指定された寸法と色空間を持つImageDataオブジェクトを返します。
データ内の各ピクセルは4つの数値で表されるため、データの長さは指定された幅の4倍の整数倍である必要があります。高さが指定されている場合、長さは幅×高さ×4の正確な長さである必要があります。
指定されたデータと寸法が一貫して解釈できない場合、または寸法のいずれかがゼロの場合、"IndexSizeError" DOMExceptionをスローします。
imagedata = context.createImageData(imagedata)
引数と同じ寸法と色空間を持つImageDataオブジェクトを返します。返されるオブジェクト内のすべてのピクセルは透明な黒です。
imagedata = context.createImageData(sw, sh [, settings])
CanvasRenderingContext2D/createImageData
すべての現在のエンジンでサポートされています。
指定された寸法を持つImageDataオブジェクトを返します。返されるオブジェクトの色空間は、contextの色空間です(settingsで上書きされていない限り)。返されるオブジェクト内のすべてのピクセルは透明な黒です。
幅または高さのいずれかの引数がゼロの場合、"IndexSizeError" DOMExceptionをスローします。
imagedata = context.getImageData(sx, sy, sw, sh [, settings])
CanvasRenderingContext2D/getImageData
すべての現在のエンジンでサポートされています。
ビットマップの指定された矩形に対応するイメージデータを含むImageDataオブジェクトを返します。返されるオブジェクトの色空間は、contextの色空間です(settingsで上書きされていない限り)。
幅または高さのいずれかの引数がゼロの場合、"IndexSizeError" DOMExceptionをスローします。
imagedata.width
すべての現在のエンジンでサポートされています。
ImageDataオブジェクト内のデータの実際の寸法をピクセル単位で返します。
imagedata.height
すべての現在のエンジンでサポートされています。
1 次元配列を返します。この配列には、0 から 255 の範囲の整数として RGBA 順でデータが含まれています。
imagedata.colorSpace
ピクセルの色空間を返します。
context.putImageData(imagedata, dx, dy [, dirtyX, dirtyY, dirtyWidth, dirtyHeight ])
CanvasRenderingContext2D/putImageData
すべての現在のエンジンでサポートされています。
指定されたImageDataオブジェクトからビットマップにデータを描画します。汚れた矩形が指定されている場合、その矩形のピクセルのみが描画されます。
このメソッド呼び出しに関して、globalAlphaとglobalCompositeOperationプロパティ、およびシャドウ属性は無視されます。キャンバス内のピクセルは、合成、アルファブレンディング、シャドウなどなしで完全に置き換えられます。
もしimagedataオブジェクトのdata属性値の[[ViewedArrayBuffer]]内部スロットが切り離されている場合、"InvalidStateError" DOMExceptionをスローします。
CanvasImageData
インターフェイスを実装するオブジェクトは、ビットマップに対するピクセルデータの読み書きのために以下のメソッドを提供します。
new ImageData(sw, sh, settings)
コンストラクタの手順は次の通りです:
sw および sh の一方または両方がゼロである場合は、 "IndexSizeError" DOMException
をスローします。
Initialize this に sw, sh, および settings が settings に設定された状態で初期化します。
new ImageData(data, sw, sh, settings)
コンストラクタの手順は次の通りです:
data のバイト数を length とします。
length が 4 の非ゼロの整数倍でない場合、 "InvalidStateError" DOMException
をスローします。
length を 4 で割ります。
length が sw の整数倍でない場合は、 "IndexSizeError" DOMException
をスローします。
この時点で、 length がゼロより大きいことが保証されているため(上記の 2 番目の手順でステップが中止されるため)、 sw がゼロの場合、この手順は例外をスローして終了します。
height を length を sw で割ったものとします。
sh が指定され、かつその値が height と等しくない場合、 "IndexSizeError" DOMException
をスローします。
Initialize this に sw, sh, および settings が settings に設定された状態で初期化します。source が data に設定された状態で初期化します。
この手順は、 this のデータを data のコピーに設定するのではなく、実際の Uint8ClampedArray
オブジェクトに設定します。
createImageData(sw, sh, settings)
メソッドの手順は次の通りです:
sw および sh の一方または両方がゼロである場合は、 "IndexSizeError" DOMException
をスローします。
Initialize newImageData に対し、 sw の絶対値、 sh の絶対値、 settings が settings に設定された状態で初期化します。defaultColorSpace が this の 色空間 に設定された状態で初期化します。
透明な黒 に newImageData のイメージデータを初期化します。
newImageData を返します。
createImageData(imagedata) メソッドの手順は次の通りです:
Initialize newImageData に対し、
imagedata の width 属性の値、
imagedata の height 属性の値、および
defaultColorSpace が
imagedata の 色空間
属性の値に設定された状態で初期化します。
透明な黒 に newImageData のイメージデータを初期化します。
newImageData を返します。
getImageData(sx, sy, sw, sh, settings)
メソッドの手順は次の通りです:
sw または sh のいずれかの引数がゼロの場合、 "IndexSizeError" DOMException
をスローします。
CanvasRenderingContext2D
の オリジン・クリーン
フラグが false に設定されている場合、 "SecurityError" DOMException
をスローします。
Initialize imageData に sw, sh, settings が settings に設定された状態で初期化します。defaultColorSpace が this の 色空間 に設定された状態で初期化します。
ソース矩形を、 4 点 (sx, sy), (sx+sw, sy), (sx+sw, sy+sh), (sx, sy+sh) の頂点とする矩形とします。
this の
出力ビットマップ
のピクセル値を、ビットマップの座標空間単位でソース矩形が指定する領域に対応する imageData のピクセル値に設定します。これを this
の 色空間 から
imageData の 色空間 へ
'relative-colorimetric' レンダリングインテントを使用して変換します。
ソース矩形の領域が 出力ビットマップ の外側にある場合、その領域の imageData のピクセル値を 透明な黒 に設定します。
imageData を返します。
ImageData オブジェクトを初期化する ために、正の整数
rows(行の数)、正の整数 pixelsPerRow(行あたりのピクセル数)、オプションの ImageDataSettings settings、オプションの Uint8ClampedArray
source、およびオプションの PredefinedColorSpace
defaultColorSpace を与えます:
source が与えられた場合、 data 属性を imageData に初期化します。
そうでない場合( source が与えられていない場合)、 imageData の data 属性を新しい Uint8ClampedArray
オブジェクトに初期化します。この Uint8ClampedArray
オブジェクトは、新しい キャンバス・ピクセル
ArrayBuffer をストレージとして使用し、ゼロの開始オフセットとストレージの長さに等しいバイト数を持つ必要があります。キャンバス・ピクセル
ArrayBuffer は、 rows × pixelsPerRow
ピクセルを格納するのに適したサイズを持つ必要があります。
キャンバス・ピクセル
ArrayBuffer を割り当てることができない場合は、JavaScript によってスローされた RangeError
を再スローして終了します。
imageData の width 属性を pixelsPerRow に初期化します。
imageData の height 属性を rows に初期化します。
settings が与えられ、 settings["colorSpace"]
が 存在する 場合、 imageData の colorSpace 属性を
settings["colorSpace"] に初期化します。
それ以外の場合、 defaultColorSpace が与えられた場合、 imageData の colorSpace
属性を defaultColorSpace に初期化します。
それ以外の場合、 imageData の colorSpace
属性を "srgb" に初期化します。
ImageData オブジェクトは シリアル化可能なオブジェクト です。それらの シリアル化手順 は、 value および
serialized を指定して次の通りです:
serialized.[[Width]] を、 value の width
属性の値に設定します。
serialized.[[Height]] を、 value の height
属性の値に設定します。
serialized.[[ColorSpace]] を、 value の colorSpace
属性の値に設定します。
それらの 逆シリアル化手順 は、 serialized, value, および targetRealm を指定して次の通りです:
value の width 属性を
serialized.[[Width]] に初期化します。
value の height 属性を
serialized.[[Height]] に初期化します。
value の colorSpace
属性を serialized.[[ColorSpace]] に初期化します。
キャンバス・ピクセル ArrayBuffer
は、左から右へ、上から下へ行ごとに、左上から始まり、各ピクセルの赤、緑、青、およびアルファ成分がその順序で各ピクセルごとに指定される ArrayBuffer
です。この配列で表される各ピクセルの各成分は 0 から 255 の範囲であり、その成分の 8 ビット値を表します。成分は 0 から始まる連続したインデックスが割り当てられ、左上のピクセルの赤成分から始まります。
putImageData() メソッドは、 ImageData 構造からのデータをレンダリングコンテキストの 出力ビットマップ に書き戻します。その引数は、 imagedata,
dx, dy, dirtyX, dirtyY, dirtyWidth, および
dirtyHeight です。
このメソッドの最後の 4 つの引数が省略された場合、それらはそれぞれ 0, 0, width メンバー、および
imagedata 構造の height
メンバーにデフォルト設定されるものとします。
このメソッドが呼び出されたときは、次のように動作しなければなりません:
buffer を imagedata の data 属性の値の
[[ViewedArrayBuffer]] 内部スロットとします。
IsDetachedBuffer(buffer) が true である場合は、 "InvalidStateError" DOMException
をスローします。
dirtyWidth が負である場合は、 dirtyX+dirtyWidth とし、 dirtyWidth を dirtyWidth の絶対値に等しいものとします。
dirtyHeight が負である場合は、 dirtyY+dirtyHeight とし、 dirtyHeight を dirtyHeight の絶対値に等しいものとします。
dirtyX が負である場合、 dirtyWidth を dirtyWidth+dirtyX とし、 dirtyX をゼロにします。
dirtyY が負である場合、 dirtyHeight を dirtyHeight+dirtyY とし、 dirtyY をゼロにします。
dirtyX+dirtyWidth が imagedata 引数の width
属性の値を超える場合、 dirtyWidth をその width 属性の値から
dirtyX の値を引いたものにします。
dirtyY+dirtyHeight が imagedata 引数の height
属性の値を超える場合、 dirtyHeight をその height 属性の値から
dirtyY の値を引いたものにします。
これらの変更後、 dirtyWidth または dirtyHeight が負またはゼロの場合は、ビットマップに影響を与えずに返します。
すべての整数値 x および y について、 dirtyX ≤ x <
dirtyX+dirtyWidth および dirtyY ≤
y < dirtyY+dirtyHeight の場合、
imagedata データ構造の キャンバス・ピクセル ArrayBuffer
に対応するピクセルの座標 (x, y) の 4 つのチャンネルを、レンダリングコンテキストの 出力ビットマップ のピクセルの座標
(dx+x, dy+y) にコピーします。
色空間間の変換と プリマルチプライド・アルファ カラー値の変換の間の損失特性のため、 putImageData()
を使用して設定されたばかりのピクセルが、完全に不透明でない場合、 getImageData()
を介して取得されると、異なる値として返される可能性があります。
現在のパス、 変換行列、 影属性、 グローバル・アルファ、 クリッピング領域、および 現在の合成およびブレンド演算子 は、このセクションで説明されているメソッドに影響を与えてはなりません。
次の例では、スクリプトがImageDataオブジェクトを生成して描画できるようにしています。
// canvasは<canvas>要素への参照です
var context = canvas. getContext( '2d' );
// 空のキャンバスを作成します
var data = context. createImageData( canvas. width, canvas. height);
// プラズマを作成します
FillPlasma( data, 'green' ); // 緑色のプラズマ
// プラズマに雲を追加します
AddCloud( data, data. width/ 2 , data. height/ 2 ); // 中央に雲を追加
// プラズマ+雲をキャンバスに描画します
context. putImageData( data, 0 , 0 );
// サポートメソッド
function FillPlasma( data, color) { ... }
function AddCloud( data, x, y) { ... }
ここでは、エッジ検出フィルターを実装するために、getImageData()とputImageData()を使用する例を示します。
<!DOCTYPE HTML>
< html lang = "en" >
< head >
< title > エッジ検出デモ</ title >
< script >
var image = new Image();
function init() {
image. onload = demo;
image. src = "image.jpeg" ;
}
function demo() {
var canvas = document. getElementsByTagName( 'canvas' )[ 0 ];
var context = canvas. getContext( '2d' );
// 画像をキャンバスに描画します
context. drawImage( image, 0 , 0 );
// 操作するために画像データを取得します
var input = context. getImageData( 0 , 0 , canvas. width, canvas. height);
// データを入れるための空のキャンバスを取得します
var output = context. createImageData( canvas. width, canvas. height);
// 便利なようにいくつかの変数をエイリアスします
// この場合、input.widthとinput.heightは
// canvas.widthとcanvas.heightに一致します
// しかし、コードを汎用的に保つために前者を使用します。
var w = input. width, h = input. height;
var inputData = input. data;
var outputData = output. data;
// エッジ検出
for ( var y = 1 ; y < h- 1 ; y += 1 ) {
for ( var x = 1 ; x < w- 1 ; x += 1 ) {
for ( var c = 0 ; c < 3 ; c += 1 ) {
var i = ( y* w + x) * 4 + c;
outputData[ i] = 127 + - inputData[ i - w* 4 - 4 ] - inputData[ i - w* 4 ] - inputData[ i - w* 4 + 4 ] +
- inputData[ i - 4 ] + 8 * inputData[ i] - inputData[ i + 4 ] +
- inputData[ i + w* 4 - 4 ] - inputData[ i + w* 4 ] - inputData[ i + w* 4 + 4 ];
}
outputData[( y* w + x) * 4 + 3 ] = 255 ; // アルファ
}
}
// 操作後に画像データを戻します
context. putImageData( output, 0 , 0 );
}
</ script >
</ head >
< body onload = "init()" >
< canvas ></ canvas >
</ body >
</ html >
次に、単色を描画して結果を読み戻す際に適用される色空間変換の例を示します。このときgetImageData()が使用されます。
<!DOCTYPE HTML>
< html lang = "en" >
< title > 色空間イメージデータデモ</ title >
< canvas ></ canvas >
< script >
const canvas = document. querySelector( 'canvas' );
const context = canvas. getContext( '2d' , { colorSpace: 'display-p3' });
// 赤い長方形を描画します。なお、16進数の色表記は
// sRGBカラーを指定します。
context. fillStyle = "#FF0000" ;
context. fillRect( 0 , 0 , 64 , 64 );
// 画像データを取得します。
const pixels = context. getImageData( 0 , 0 , 1 , 1 );
// これは'display-p3'を出力します。これは、キャンバスの色空間で画像データが
// 返されるデフォルト動作を反映しています。
console. log( pixels. colorSpace);
// これは値234、51、および35を出力します。
// これは'display-p3'に変換された赤の塗りつぶし色を反映しています。
console. log( pixels. data[ 0 ]);
console. log( pixels. data[ 1 ]);
console. log( pixels. data[ 2 ]);
</ script >
context.globalAlpha [ = value ]
CanvasRenderingContext2D/globalAlpha
すべての現行エンジンでサポートされています。
現在のレンダリング操作に適用されるグローバルアルファ値を返します。
設定すると、グローバルアルファ値を変更できます。範囲外の値 (0.0 ~ 1.0) は無視されます。
context.globalCompositeOperation [ = value ]
CanvasRenderingContext2D/globalCompositeOperation
すべての現行エンジンでサポートされています。
現在の合成およびブレンド操作を返します。これらの値は、Compositing and Blendingで定義されています。[COMPOSITE]
設定すると、現在の合成およびブレンド操作を変更できます。不明な値は無視されます。
CanvasCompositingインターフェースを実装するオブジェクトは、すべての描画操作に影響を与えるグローバルアルファ値と現在の合成およびブレンド操作値を持っています。
グローバルアルファ値は、出力ビットマップに合成される前に形状や画像に適用されるアルファ値を指定します。この値は、0.0(完全に透明)から1.0(追加の透明性なし)までの範囲で、初期値は1.0である必要があります。
globalAlphaゲッターステップは、thisのグローバルアルファを返すことです。
globalAlphaセッターステップは次のとおりです:
現在の合成およびブレンド操作値は、出力ビットマップに描画される形状や画像の描画方法を制御します。これには、グローバルアルファおよび現在の変換行列が適用されます。初期設定では、「source-over」に設定されている必要があります。
globalCompositeOperationゲッターステップは、thisの現在の合成およびブレンド操作を返すことです。
globalCompositeOperationセッターステップは次のとおりです:
指定された値が完全に一致するいずれかの値ではない場合、処理を終了します。[COMPOSITE]
それ以外の場合は、thisの現在の合成およびブレンド操作を指定された値に設定します。
context.imageSmoothingEnabled [ = value ]
CanvasRenderingContext2D/imageSmoothingEnabled
すべての現行エンジンでサポートされています。
パターンフィルと drawImage()
メソッドが、画像のスケーリング時に、ピクセルが表示と正確に一致しない場合に画像をスムージングするかどうかを返します。
設定すると、画像がスムージングされるか(true)どうか(false)を変更できます。
context.imageSmoothingQuality [ = value ]
CanvasRenderingContext2D/imageSmoothingQuality
現在の画像スムージングの品質設定を返します。
設定すると、画像スムージングの優先品質を変更できます。利用可能な値は、"low"、"medium"、および"high"です。不明な値は無視されます。
CanvasImageSmoothingインターフェースを実装するオブジェクトには、画像スムージングの方法を制御する属性があります。
imageSmoothingEnabled属性は、取得時に最後に設定された値を返します。設定時には、新しい値に設定される必要があります。CanvasImageSmoothingインターフェースを実装するオブジェクトが作成されたとき、この属性は
true に設定されている必要があります。
imageSmoothingQuality属性は、取得時に最後に設定された値を返します。設定時には、新しい値に設定される必要があります。CanvasImageSmoothingインターフェースを実装するオブジェクトが作成されたとき、この属性は"low"に設定されている必要があります。
CanvasShadowStyles
インターフェースを実装するオブジェクトのすべての描画操作は、4つのグローバルシャドウ属性の影響を受けます。
context.shadowColor [ = value ]
CanvasRenderingContext2D/shadowColor
すべての現行エンジンでサポートされています。
現在のシャドウの色を返します。
設定することで、シャドウの色を変更できます。CSSカラーとして解析できない値は無視されます。
context.shadowOffsetX [ = value ]
CanvasRenderingContext2D/shadowOffsetX
すべての現行エンジンでサポートされています。
現在のシャドウのオフセットを返します。
設定することで、シャドウのオフセットを変更できます。有限の数値でない値は無視されます。
context.shadowOffsetY [ = value ]
CanvasRenderingContext2D/shadowOffsetY
すべての現行エンジンでサポートされています。
現在のシャドウのオフセットを返します。
設定することで、シャドウのオフセットを変更できます。有限の数値でない値は無視されます。
context.shadowBlur [ = value ]
CanvasRenderingContext2D/shadowBlur
すべての現行エンジンでサポートされています。
現在のシャドウに適用されるぼかしのレベルを返します。
設定することで、ぼかしレベルを変更できます。有限でないか、ゼロ以上でない値は無視されます。
CanvasShadowStyles
インターフェースを実装するオブジェクトには、CSSカラーである シャドウカラー
が関連付けられています。初期状態では、この値は 透過黒
でなければなりません。
shadowColor の getter ステップは、色のシリアライゼーション を返します。shadowColor の setter
ステップは、次の通りです:
context を this の canvas
属性の値に設定します(要素である場合)、それ以外の場合は null に設定します。
parsedValue を CSSカラー値を解析 した結果に設定します(context が null でない場合)。
parsedValue が失敗の場合、return します。
shadowOffsetX および shadowOffsetY
属性は、それぞれシャドウが正の水平方向および正の垂直方向にオフセットされる距離を指定します。これらの値は座標空間単位で指定され、現在の変換マトリックスの影響を受けません。
コンテキストが作成されると、シャドウオフセット属性の初期値は 0 に設定されている必要があります。
取得時には、現在の値を返します。設定時には、設定される属性は新しい値に設定される必要があります。ただし、その値が無限大または NaN の場合、新しい値は無視されなければなりません。
shadowBlur
属性は、ぼかし効果のレベルを指定します。(単位は座標空間単位に対応しておらず、現在の変換マトリックスの影響を受けません。)
コンテキストが作成されると、shadowBlur
属性は初期状態で 0 に設定されている必要があります。
取得時には、属性は現在の値を返す必要があります。設定時には、その属性は新しい値に設定される必要がありますが、その値が負の数、無限大、または NaN の場合、新しい値は無視されなければなりません。
シャドウが描画されるのは 、シャドウカラー のアルファコンポーネントの不透明度がゼロでなく、かつ shadowBlur がゼロでない場合、または
shadowOffsetX
がゼロでない場合、または shadowOffsetY
がゼロでない場合に限られます。
シャドウが描画される 場合、以下のようにレンダリングされる必要があります:
A を、シャドウが作成されるソース画像が描画された無限大の 透過黒 ビットマップに設定します。
B を、座標空間と原点が A と同一である無限大の 透過黒 ビットマップに設定します。
shadowOffsetX
で正の x 方向に、shadowOffsetY
で正の y 方向にオフセットして、A のアルファチャネルを B にコピーします。
shadowBlur が 0
より大きい場合:
σ を shadowBlur
の値の半分に設定します。
B に対して 2D ガウスぼかしを実行し、標準偏差として σ を使用します。
ユーザーエージェントは、ガウスぼかし操作中にハードウェアの制限を超えることを避けるために、σ の値を実装固有の最大値に制限することができます。
B のすべてのピクセルの赤、緑、および青のコンポーネントを シャドウカラー の赤、緑、および青のコンポーネントに設定します。
B のすべてのピクセルのアルファコンポーネントを シャドウカラー のアルファコンポーネントで乗算します。
シャドウはビットマップ B にあり、以下で説明する 描画モデル の一部としてレンダリングされます。
現在の合成およびブレンドオペレーター が "コピー"
である場合、シャドウは実際にはレンダリングされません(形状がシャドウを上書きするため)。
CanvasFilters
インターフェースを実装するオブジェクトに対するすべての描画操作は、グローバルな filter 属性の影響を受けます。
context.filter [ = value ]
CanvasRenderingContext2D/filter
現在のフィルターを返します。
設定することで、フィルターを変更できます。値は "none" という文字列、または <filter-value-list> として解析可能な文字列である必要があります。他の値は無視されます。
そのようなオブジェクトには、現在のフィルター と呼ばれる関連付けられた文字列があります。現在のフィルター は初期状態で
"none" に設定されています。現在のフィルター の値が "none" であるとき、フィルターはコンテキストで無効になります。
filter の getter ステップは、this の 現在のフィルター を返します。
filter の setter ステップは次の通りです:
parsedValue を、与えられた値を CSS 構文に従って解析 した結果に設定します。'inherit' や 'initial' などのプロパティに依存しないスタイルシートの構文が含まれている場合、この解析は失敗しなければなりません。
parsedValue が失敗の場合、return します。
context.
はコンテキストのフィルターを無効にしますが、filter
= "none"context.、filter
=
""context.、およびfilter
=
nullcontext.はすべて解析不可能な入力と見なされ、現在のフィルター の値は変更されません。
filter
= undefined
現在のフィルター の値に使用される座標は、1 ピクセルが 1 SVG ユーザースペース単位および 1 キャンバス座標空間単位に相当するように解釈されます。フィルターの座標は、現在の変換マトリックスの影響を受けません。現在の変換マトリックスはフィルターの入力のみに影響を与えます。フィルターは 出力ビットマップ の座標空間で適用されます。
現在のフィルター の値が、<filter-value-list> として解析可能な文字列で、長さをパーセンテージや 'em' または 'ex' 単位で定義する場合、これらは属性が設定された時点での計算値に対して相対的に解釈されなければなりません。これらの計算値が特定のケースで未定義の場合(例えば、フォントスタイルソースオブジェクトが要素でないか、レンダリングされていないため)、相対的なキーワードはフォント
属性のデフォルト値に対して解釈されなければなりません。'larger' および 'smaller' キーワードはサポートされていません。
現在のフィルター の値が、同じドキュメント内の SVG フィルターへの参照を含む<filter-value-list> として解析可能な文字列であり、その SVG フィルターが変更された場合、次の描画操作には変更されたフィルターが使用されます。
現在のフィルター の値が、外部リソースドキュメント内の SVG フィルターへの参照を含む<filter-value-list> として解析可能な文字列であり、そのドキュメントが描画操作の実行時に読み込まれていない場合、描画操作はフィルタリングなしで続行しなければなりません。
このセクションは規範的ではありません。
外部定義のフィルターが読み込み完了するまで描画はフィルタ値 "none"
を使用して実行されるため、著者はこのようなフィルターが読み込み完了したかどうかを確認してから描画操作を続行することを検討するかもしれません。これを達成する一つの方法は、外部定義のフィルターを同じページ内の別の場所で、例えば
load イベントを送信する要素(例:SVG use
要素)で読み込んで、load イベントが発生するのを待つことです。
シェイプや画像がペイントされる際、ユーザーエージェントは以下の手順に従って処理を行わなければなりません(あるいはそのように処理しているかのように振る舞わなければなりません):
無限の透明な黒ビットマップにシェイプや画像をレンダリングし、イメージ A を作成します。これについては前述のセクションで説明されています。シェイプの場合、現在の塗りつぶし、ストローク、ラインスタイルが適用され、ストロークも現在の変換マトリックスの影響を受けなければなりません。
現在のフィルター が
"none" 以外の値に設定され、参照される外部定義のフィルターがすべて読み込まれている場合、イメージ A を 現在のフィルター
の入力として使用し、イメージ B を作成します。現在のフィルター が <filter-value-list> として解析可能な文字列である場合、SVG と同じ方法で 現在のフィルター
を使用して描画を行います。
それ以外の場合、B は A の別名として扱います。
シャドウが描かれる場合、現在のシャドウスタイルを使用してイメージ B からシャドウをレンダリングし、イメージ C を作成します。
シャドウが描かれる場合、C
の各ピクセルのアルファ成分に グローバルアルファ
を掛けます。
シャドウが描かれる場合、クリッピング領域内でイメージ C を現在の出力ビットマップ に 現在の合成およびブレンド操作 を使用して合成します。
B の各ピクセルのアルファ成分に グローバルアルファ
を掛けます。
B を クリッピング領域 内で現在の出力ビットマップ に 現在の合成およびブレンド操作 を使用して合成します。
出力ビットマップ に合成する際、出力ビットマップ 外に出るピクセルは破棄しなければなりません。
キャンバスがインタラクティブである場合、著者は、上記の例のように、キャンバスの各フォーカス可能な部分に対応するフォーカス可能な要素を要素のフォールバックコンテンツに含めるべきです。
フォーカスリングをレンダリングする際、フォーカスリングがネイティブのフォーカスリングの外観を持つようにするために、著者はリングが描かれる要素を渡してdrawFocusIfNeeded()メソッドを使用すべきです。このメソッドは、要素がフォーカスされている場合にのみフォーカスリングを描画するため、要素がフォーカスされているかどうかを事前に確認せずに、要素を描画するたびに単に呼び出すことができます。
著者は、canvas要素を使用してテキスト編集コントロールを実装することを避けるべきです。この方法には多くの欠点があります:
これは非常に大変な作業であり、著者は、代わりにinput要素、textarea要素、またはcontenteditable属性を使用することで、このような作業を避けることを強く推奨します。
このセクションは規範的ではありません。
ここでは、キャンバスを使用して美しい輝く線 を描画するスクリプトの例です。
< canvas width = "800" height = "450" ></ canvas >
< script >
var context = document. getElementsByTagName( 'canvas' )[ 0 ]. getContext( '2d' );
var lastX = context. canvas. width * Math. random();
var lastY = context. canvas. height * Math. random();
var hue = 0 ;
function line() {
context. save();
context. translate( context. canvas. width/ 2 , context. canvas. height/ 2 );
context. scale( 0.9 , 0.9 );
context. translate( - context. canvas. width/ 2 , - context. canvas. height/ 2 );
context. beginPath();
context. lineWidth = 5 + Math. random() * 10 ;
context. moveTo( lastX, lastY);
lastX = context. canvas. width * Math. random();
lastY = context. canvas. height * Math. random();
context. bezierCurveTo( context. canvas. width * Math. random(),
context. canvas. height * Math. random(),
context. canvas. width * Math. random(),
context. canvas. height * Math. random(),
lastX, lastY);
hue = hue + 10 * Math. random();
context. strokeStyle = 'hsl(' + hue + ', 50%, 50%)' ;
context. shadowColor = 'white' ;
context. shadowBlur = 10 ;
context. stroke();
context. restore();
}
setInterval( line, 50 );
function blank() {
context. fillStyle = 'rgba(0,0,0,0.1)' ;
context. fillRect( 0 , 0 , context. canvas. width, context. canvas. height);
}
setInterval( blank, 40 );
</ script >
キャンバスの2Dレンダリングコンテキストは、スプライトベースのゲームに頻繁に使用されます。次の例はそのデモンストレーションです。
この例のソースコードは次のとおりです:
<!DOCTYPE HTML>
< html lang = "en" >
< meta charset = "utf-8" >
< title > Blue Robot Demo</ title >
< style >
html { overflow : hidden ; min-height : 200 px ; min-width : 380 px ; }
body { height : 200 px ; position : relative ; margin : 8 px ; }
. buttons { position : absolute ; bottom : 0 px ; left : 0 px ; margin : 4 px ; }
</ style >
< canvas width = "380" height = "200" ></ canvas >
< script >
var Landscape = function ( context, width, height) {
this . offset = 0 ;
this . width = width;
this . advance = function ( dx) {
this . offset += dx;
};
this . horizon = height * 0.7 ;
// This creates the sky gradient (from a darker blue to white at the bottom)
this . sky = context. createLinearGradient( 0 , 0 , 0 , this . horizon);
this . sky. addColorStop( 0.0 , 'rgb(55,121,179)' );
this . sky. addColorStop( 0.7 , 'rgb(121,194,245)' );
this . sky. addColorStop( 1.0 , 'rgb(164,200,214)' );
// this creates the grass gradient (from a darker green to a lighter green)
this . earth = context. createLinearGradient( 0 , this . horizon, 0 , height);
this . earth. addColorStop( 0.0 , 'rgb(81,140,20)' );
this . earth. addColorStop( 1.0 , 'rgb(123,177,57)' );
this . paintBackground = function ( context, width, height) {
// first, paint the sky and grass rectangles
context. fillStyle = this . sky;
context. fillRect( 0 , 0 , width, this . horizon);
context. fillStyle = this . earth;
context. fillRect( 0 , this . horizon, width, height- this . horizon);
// then, draw the cloudy banner
// we make it cloudy by having the draw text off the top of the
// canvas, and just having the blurred shadow shown on the canvas
context. save();
context. translate( width- (( this . offset+ ( this . width* 3.2 )) % ( this . width* 4.0 )) + 0 , 0 );
context. shadowColor = 'white' ;
context. shadowOffsetY = 30 + this . horizon/ 3 ; // offset down on canvas
context. shadowBlur = '5' ;
context. fillStyle = 'white' ;
context. textAlign = 'left' ;
context. textBaseline = 'top' ;
context. font = '20px sans-serif' ;
context. fillText( 'WHATWG ROCKS' , 10 , - 30 ); // text up above canvas
context. restore();
// then, draw the background tree
context. save();
context. translate( width- (( this . offset+ ( this . width* 0.2 )) % ( this . width* 1.5 )) + 30 , 0 );
context. beginPath();
context. fillStyle = 'rgb(143,89,2)' ;
context. lineStyle = 'rgb(10,10,10)' ;
context. lineWidth = 2 ;
context. rect( 0 , this . horizon+ 5 , 10 , - 50 ); // trunk
context. fill();
context. stroke();
context. beginPath();
context. fillStyle = 'rgb(78,154,6)' ;
context. arc( 5 , this . horizon- 60 , 30 , 0 , Math. PI* 2 ); // leaves
context. fill();
context. stroke();
context. restore();
};
this . paintForeground = function ( context, width, height) {
// draw the box that goes in front
context. save();
context. translate( width- (( this . offset+ ( this . width* 0.7 )) % ( this . width* 1.1 )) + 0 , 0 );
context. beginPath();
context. rect( 0 , this . horizon - 5 , 25 , 25 );
context. fillStyle = 'rgb(220,154,94)' ;
context. lineStyle = 'rgb(10,10,10)' ;
context. lineWidth = 2 ;
context. fill();
context. stroke();
context. restore();
};
};
</ script >
< script >
var BlueRobot = function () {
this . sprites = new Image();
this . sprites. src = 'blue-robot.png' ; // this sprite sheet has 8 cells
this . targetMode = 'idle' ;
this . walk = function () {
this . targetMode = 'walk' ;
};
this . stop = function () {
this . targetMode = 'idle' ;
};
this . frameIndex = {
'idle' : [ 0 ], // first cell is the idle frame
'walk' : [ 1 , 2 , 3 , 4 , 5 , 6 ], // the walking animation is cells 1-6
'stop' : [ 7 ], // last cell is the stopping animation
};
this . mode = 'idle' ;
this . frame = 0 ; // index into frameIndex
this . tick = function () {
// this advances the frame and the robot
// the return value is how many pixels the robot has moved
this . frame += 1 ;
if ( this . frame >= this . frameIndex[ this . mode]. length) {
// we've reached the end of this animation cycle
this . frame = 0 ;
if ( this . mode != this . targetMode) {
// switch to next cycle
if ( this . mode == 'walk' ) {
// we need to stop walking before we decide what to do next
this . mode = 'stop' ;
} else if ( this . mode == 'stop' ) {
if ( this . targetMode == 'walk' )
this . mode = 'walk' ;
else
this . mode = 'idle' ;
} else if ( this . mode == 'idle' ) {
if ( this . targetMode == 'walk' )
this . mode = 'walk' ;
}
}
}
if ( this . mode == 'walk' )
return 8 ;
return 0 ;
},
this . paint = function ( context, x, y) {
if ( ! this . sprites. complete) return ;
// draw the right frame out of the sprite sheet onto the canvas
// we assume each frame is as high as the sprite sheet
// the x,y coordinates give the position of the bottom center of the sprite
context. drawImage( this . sprites,
this . frameIndex[ this . mode][ this . frame] * this . sprites. height, 0 , this . sprites. height, this . sprites. height,
x- this . sprites. height/ 2 , y- this . sprites. height, this . sprites. height, this . sprites. height);
};
};
</ script >
< script >
var canvas = document. getElementsByTagName( 'canvas' )[ 0 ];
var context = canvas. getContext( '2d' );
var landscape = new Landscape( context, canvas. width, canvas. height);
var blueRobot = new BlueRobot();
// paint when the browser wants us to, using requestAnimationFrame()
function paint() {
context. clearRect( 0 , 0 , canvas. width, canvas. height);
landscape. paintBackground( context, canvas. width, canvas. height);
blueRobot. paint( context, canvas. width/ 2 , landscape. horizon* 1.1 );
landscape. paintForeground( context, canvas. width, canvas. height);
requestAnimationFrame( paint);
}
paint();
// but tick every 100ms, so that we don't slow down when we don't paint
setInterval( function () {
var dx = blueRobot. tick();
landscape. advance( dx);
}, 100 );
</ script >
< p class = "buttons" >
< input type = button value = "Walk" onclick = "blueRobot.walk()" >
< input type = button value = "Stop" onclick = "blueRobot.stop()" >
< footer >
< small > Blue Robot Player Sprite by < a href = "https://johncolburn.deviantart.com/" > JohnColburn</ a > .
Licensed under the terms of the Creative Commons Attribution Share-Alike 3.0 Unported license.</ small >
< small > This work is itself licensed under a < a rel = "license" href = "https://creativecommons.org/licenses/by-sa/3.0/" > Creative
Commons Attribution-ShareAlike 3.0 Unported License</ a > .</ small >
</ footer >
ImageBitmap レンダリングコンテキストImageBitmapRenderingContextは、drawImage()メソッドとは異なり、中間合成を避けることで、全体のメモリ消費を抑え、パフォーマンスを向上させるための低オーバーヘッドな手法を提供する、パフォーマンス指向のインターフェイスです。
例えば、img要素をキャンバスに画像リソースを取得するための中間として使用すると、メモリ内にデコードされた画像のコピーが2つ存在することになります:
img要素のコピーとキャンバスのバッキングストア内のものです。このメモリコストは、非常に大きな画像を扱う場合には負担が大きくなります。これを回避するためには、ImageBitmapRenderingContextを使用することができます。
ImageBitmapRenderingContextを使用して、メモリとCPUの効率を考慮した方法で画像をJPEGフォーマットにトランスコードする方法を以下に示します:
createImageBitmap( inputImageBlob). then( image => {
const canvas = document. createElement( 'canvas' );
const context = canvas. getContext( 'bitmaprenderer' );
context. transferFromImageBitmap( image);
canvas. toBlob( outputJPEGBlob => {
// Do something with outputJPEGBlob.
}, 'image/jpeg' );
});
ImageBitmapRenderingContext
インターフェースすべての現在のエンジンでサポートされています。
[Exposed =(Window ,Worker )]
interface ImageBitmapRenderingContext {
readonly attribute (HTMLCanvasElement or OffscreenCanvas ) canvas ;
undefined transferFromImageBitmap (ImageBitmap ? bitmap );
};
dictionary ImageBitmapRenderingContextSettings {
boolean alpha = true ;
};
context = canvas.getContext('bitmaprenderer' [, { [ alpha: false ] } ])
ImageBitmapRenderingContext
オブジェクトを返します。このオブジェクトは特定の
canvas
要素に永久にバインドされます。
もし
alpha
設定が提供され、false に設定されている場合、キャンバスは常に不透明であることが強制されます。
context.canvas
canvas
要素を返します。このコンテキストにバインドされています。
context.transferFromImageBitmap(imageBitmap)
ImageBitmapRenderingContext/transferFromImageBitmap
すべての現在のエンジンでサポートされています。
imageBitmap から context へと ビットマップデータ
を転送し、このビットマップが context にバインドされている
canvas
要素の内容になります。
context.transferFromImageBitmap(null)
context にバインドされている
canvas
要素の内容を、対応するサイズの 透明な黒 ビットマップに置き換えます。このサイズは、
幅
および
高さ
コンテンツ属性に対応します。
canvas 属性は、オブジェクトが作成されたときに初期化された値を返さなければなりません。
ImageBitmapRenderingContext
オブジェクトには、出力ビットマップがあります。これは、ビットマップデータへの参照です。
ImageBitmapRenderingContext
オブジェクトには、ビットマップモードもあり、これは valid または blank に設定できます。valid の値は、コンテキストの
出力ビットマップ
が、transferFromImageBitmap()
を通じて取得されたビットマップデータを参照していることを示します。blank の値は、コンテキストの
出力ビットマップ
がデフォルトの透明なビットマップであることを示します。
ImageBitmapRenderingContext
オブジェクトには、alpha フラグもあり、これは true または false に設定できます。ImageBitmapRenderingContext
オブジェクトの alpha フラグが false
に設定されている場合、コンテキストがバインドされている canvas
要素の内容は、コンテキストの 出力ビットマップ
を同じサイズの 不透明な黒 のビットマップに source-over 合成演算子を使用して合成することによって取得されます。alpha フラグが true
に設定されている場合、出力ビットマップ
がコンテキストにバインドされている canvas
要素の内容として使用されます。[COMPOSITE]
不透明な黒 のビットマップに対する合成のステップは、他の手段によってより効率的に同等の結果が得られる場合には省略されるべきです。
ユーザーエージェントが ImageBitmapRenderingContext
の出力ビットマップを設定する ことが要求された場合、context 引数が ImageBitmapRenderingContext
オブジェクトであり、オプションの引数 bitmap が ビットマップデータ
を参照している場合、以下の手順を実行しなければなりません:
もし bitmap 引数が提供されていない場合、次のようにします:
もし bitmap 引数が提供されている場合、次のようにします:
context の 出力ビットマップ を、bitmap と同じ基盤となるビットマップデータを参照するように設定します。コピーは行われません。
origin-clean フラグは、bitmap のビットマップデータに含まれ、context の 出力ビットマップ に参照されます。
ImageBitmapRenderingContext 作成アルゴリズム
は、target および options を引数として渡され、次の手順を実行します:
settings を、options を辞書型 ImageBitmapRenderingContextSettings
に変換した結果とします。(これにより例外が発生する可能性があります。)
context を新しい ImageBitmapRenderingContext
オブジェクトとします。
context の canvas
属性を target を指すように初期化します。
context の 出力ビットマップ を、target のビットマップと同じに設定します(つまり、共有される)。
ImageBitmapRenderingContext の出力ビットマップを設定する ステップを実行し、context を渡します。
context の alpha フラグを true に初期化します。
settings の各メンバーを次のように処理します:
alpha
context を返します。
transferFromImageBitmap(bitmap)
メソッドが呼び出されたとき、次の手順を実行しなければなりません:
bitmapContext を ImageBitmapRenderingContext
オブジェクトとします。このオブジェクト上で transferFromImageBitmap()
メソッドが呼び出されました。
もし bitmap が null である場合、ImageBitmapRenderingContext の出力ビットマップを設定する ステップを実行し、bitmapContext を context 引数とし、bitmap 引数を指定せずに返します。
もし bitmap の [[Detached]] 内部スロットの値が true に設定されている場合、"InvalidStateError" DOMException
をスローします。
ImageBitmapRenderingContext の出力ビットマップを設定する ステップを実行し、context 引数に bitmapContext を、bitmap 引数には bitmap の基盤となる ビットマップデータ を指定します。
bitmap の [[Detached]] 内部スロットの値を true に設定します。
bitmap の ビットマップデータ を解除します。
OffscreenCanvas
インターフェースすべての現行エンジンでサポートされています。
typedef (OffscreenCanvasRenderingContext2D or ImageBitmapRenderingContext or WebGLRenderingContext or WebGL2RenderingContext or GPUCanvasContext ) OffscreenRenderingContext ;
dictionary ImageEncodeOptions {
DOMString type = "image/png";
unrestricted double quality ;
};
enum OffscreenRenderingContextId { " 2d " , " bitmaprenderer " , " webgl " , " webgl2 " , " webgpu " };
[Exposed =(Window ,Worker ), Transferable ]
interface OffscreenCanvas : EventTarget {
constructor ([EnforceRange ] unsigned long long width , [EnforceRange ] unsigned long long height );
attribute [EnforceRange ] unsigned long long width ;
attribute [EnforceRange ] unsigned long long height ;
OffscreenRenderingContext ? getContext (OffscreenRenderingContextId contextId , optional any options = null );
ImageBitmap transferToImageBitmap ();
Promise <Blob > convertToBlob (optional ImageEncodeOptions options = {});
attribute EventHandler oncontextlost ;
attribute EventHandler oncontextrestored ;
};
OffscreenCanvas は
EventTarget
であり、OffscreenCanvasRenderingContext2D
と WebGL の両方がイベントを発生させることができます。OffscreenCanvasRenderingContext2D
は contextlost と
contextrestored
イベントを発生させ、WebGL は webglcontextlost と webglcontextrestored を発生させることができます。[WEBGL]
OffscreenCanvas
オブジェクトは、HTMLCanvasElement
と同様にレンダリングコンテキストを作成するために使用されますが、DOM との接続はありません。これにより、ワーカー内でキャンバスレンダリングコンテキストを使用することが可能になります。
OffscreenCanvas
オブジェクトは、通常 DOM 内にある プレースホルダー canvas
要素への弱い参照を保持する場合があります。その埋め込まれたコンテンツは OffscreenCanvas
オブジェクトによって提供されます。OffscreenCanvas
オブジェクトのビットマップは、プレースホルダー canvas 要素に、その 関連するエージェントの イベントループの レンダリングの更新
の手順の一環としてプッシュされます。
offscreenCanvas = new OffscreenCanvas(width, height)
OffscreenCanvas/OffscreenCanvas
すべての現行エンジンでサポートされています。
DOM に接続されていない、プレースホルダー canvas
要素にリンクされていない新しい OffscreenCanvas
オブジェクトを返します。このビットマップのサイズは width および height 引数によって決定されます。
context = offscreenCanvas.getContext(contextId [, options ])
すべての現行エンジンでサポートされています。
OffscreenCanvas
オブジェクト上での描画用 API を公開するオブジェクトを返します。contextId は、希望する API を指定します: "2d"、"bitmaprenderer"、"webgl"、"webgl2"、または
"webgpu"
です。options はその API によって処理されます。
この仕様は、以下で定義されている "2d"
コンテキストを定義していますが、これは 2d
コンテキストと似ていますが異なります。WebGL 仕様は、"webgl"
および "webgl2"
コンテキストを定義しています。WebGPU は "webgpu"
コンテキストを定義しています。[WEBGL][WEBGPU]
キャンバスがすでに別のコンテキストタイプで初期化されている場合 (例: "2d"
コンテキストを取得した後に "webgl"
コンテキストを取得しようとする場合など)、null を返します。
OffscreenCanvas
オブジェクトには、作成時に初期化される内部 ビットマップ があります。ビットマップ の幅と高さは、width
および height
属性の値と等しくなります。ビットマップのすべてのピクセルは、初期状態では 透明な黒 です。
OffscreenCanvas
オブジェクトには、レンダリングコンテキストがバインドされる可能性があります。初期状態では、バインドされたレンダリングコンテキストはありません。レンダリングコンテキストがあるかどうか、またそれがどのような種類のレンダリングコンテキストであるかを記録するために、OffscreenCanvas
オブジェクトには コンテキストモード もあり、初期状態では なし ですが、この仕様で定義されたアルゴリズムによって 2d、bitmaprenderer、webgl、webgl2、webgpu、または detached
に変更される可能性があります。
コンストラクター OffscreenCanvas(width, height)
は、呼び出されたときに、ビットマップ
が width および height で指定された寸法の 透明な黒
ピクセルの長方形配列に初期化された、新しい OffscreenCanvas
オブジェクトを作成し、width
および height
属性をそれぞれ width および height に初期化しなければなりません。
OffscreenCanvas
オブジェクトは 転送可能です。value および dataHolder
が与えられたときの 転送手順 は次の通りです。
もし value の コンテキストモード が none に等しくない場合は、"InvalidStateError" DOMException
をスローします。
value の ビットマップ の寸法を width および height に設定します。
value の ビットマップ を解除します。
dataHolder.[[Width]] に width を、dataHolder.[[Height]] に height を設定します。
dataHolder.[[PlaceholderCanvas]] に、value に プレースホルダー canvas 要素
がある場合はそれへの弱い参照を設定し、ない場合は null を設定します。
dataHolder および value が与えられたときの 転送受け取り手順 は次の通りです。
value の ビットマップ を dataHolder.[[Width]] によって与えられた幅、および dataHolder.[[Height]] によって与えられた高さを持つ 透明な黒 のピクセルの長方形配列に初期化します。
もし dataHolder.[[PlaceholderCanvas]] が null でない場合、value の プレースホルダー canvas 要素 を
dataHolder.[[PlaceholderCanvas]] に設定します(弱い参照のセマンティクスを維持しながら)。
getContext(contextId, options)
メソッドは、OffscreenCanvas
オブジェクトが呼び出されたときに次の手順を実行しなければなりません。
options が オブジェクト でない場合、options を null に設定します。
options を JavaScript の値に変換 する結果として options を設定します。
以下の表の列ヘッダーがこの OffscreenCanvas
オブジェクトの コンテキストモード に一致し、行ヘッダーが
contextId に一致するセル内の手順を実行します。
| none | 2d | bitmaprenderer | webgl または webgl2 | webgpu | detached | |
|---|---|---|---|---|---|---|
"2d"
|
| 同じ最初の引数でメソッドが呼び出された最後のときに返されたオブジェクトと同じオブジェクトを返します。 | null を返します。 | null を返します。 | null を返します。 | "InvalidStateError" DOMException
をスローします。
|
"bitmaprenderer"
|
| null を返します。 | 同じ最初の引数でメソッドが呼び出された最後のときに返されたオブジェクトと同じオブジェクトを返します。 | null を返します。 | null を返します。 | "InvalidStateError" DOMException
をスローします。
|
"webgl" または "webgl2"
| null を返します。 | null を返します。 | 同じ最初の引数でメソッドが呼び出された最後のときに返された値と同じ値を返します。 | null を返します。 | "InvalidStateError" DOMException
をスローします。
| |
"webgpu"
|
| null を返します。 | null を返します。 | null を返します。 | 同じ最初の引数でメソッドが呼び出された最後のときに返された値と同じ値を返します。 | "InvalidStateError" DOMException
をスローします。
|
offscreenCanvas.width [
= value ]
すべての現在のエンジンでサポートされています。
offscreenCanvas.height [
= value ]
すべての現在のエンジンでサポートされています。
これらの属性は、OffscreenCanvas
オブジェクトのビットマップの寸法を返します。
これらの値を設定することで、指定された寸法の新しいビットマップで 置き換えることができます(効果的にリサイズします)。新しいビットマップは、透明な黒です。
もし、OffscreenCanvas
オブジェクトの width または height
属性が設定された場合(新しい値または以前と同じ値に設定)、OffscreenCanvas
オブジェクトの コンテキストモード が 2d
であれば、レンダリングコンテキストをデフォルトの状態にリセットし、OffscreenCanvas
オブジェクトの ビットマップ を
width
および height
属性の新しい値にリサイズします。
"webgl"
および "webgl2"
コンテキストのリサイズ動作は、WebGL 仕様で定義されています。[WEBGL]
"webgpu"
コンテキストのリサイズ動作は WebGPU で定義されています。[WEBGPU]
もし、OffscreenCanvas
オブジェクトの寸法が変更された場合、
プレースホルダーcanvas要素が存在する場合、
プレースホルダーcanvas要素の
自然なサイズ は、
OffscreenCanvas の
関連エージェントの イベントループ の
レンダリングの更新
ステップ中にのみ更新されます。
promise = offscreenCanvas.convertToBlob([options])
すべての現在のエンジンでサポートされています。
このプロミスは、新しいBlobオブジェクトで解決され、OffscreenCanvasオブジェクト内の画像を含むファイルを表します。
引数としてオプションの辞書が提供される場合、その辞書は作成される画像ファイルのエンコードオプションを制御します。typeフィールドはファイル形式を指定し、デフォルト値は
"image/png"
です。このタイプは、要求されたタイプがサポートされていない場合にも使用されます。画像形式が可変品質をサポートしている場合(例えば、"image/jpeg")、qualityフィールドは、生成される画像の希望品質レベルを示す
0.0 から 1.0 までの範囲の数値です。
canvas.transferToImageBitmap()
OffscreenCanvas/transferToImageBitmap
すべての現在のエンジンでサポートされています。
新しく作成されたImageBitmapオブジェクトを返し、OffscreenCanvasオブジェクト内の画像を保持します。OffscreenCanvasオブジェクト内の画像は、新しい空白の画像に置き換えられます。
convertToBlob(options)メソッドは、呼び出されると、次のステップを実行する必要があります。
このOffscreenCanvasオブジェクトの[[Detached]]内部スロットの値がtrueに設定されている場合、拒否されたプロミスを返し、"InvalidStateError"DOMExceptionを発生させます。
このOffscreenCanvasオブジェクトのコンテキストモードが2dであり、レンダリングコンテキストのビットマップのオリジンクリーンフラグがfalseに設定されている場合、拒否されたプロミスを返し、"SecurityError"
DOMExceptionを発生させます。
このOffscreenCanvasオブジェクトのビットマップにピクセルがない場合(つまり、水平寸法または垂直寸法のいずれかがゼロの場合)、拒否されたプロミスを返し、"IndexSizeError"DOMExceptionを発生させます。
このOffscreenCanvasオブジェクトのビットマップのコピーをbitmapに設定します。
新しいプロミスオブジェクトをresultに設定します。
次のステップを並列で実行します。
bitmapをファイルとしてシリアル化したものをfileに設定し、optionsのtypeとqualityが存在する場合はそれを使用します。
次のステップを実行するために、エレメントタスクをキューに入れます。
もしfileがnullの場合、resultを拒否し、"EncodingError"DOMExceptionを発生させます。
それ以外の場合、resultを解決し、新しいBlobオブジェクトを返します。このオブジェクトは、このOffscreenCanvasオブジェクトの関連する領域で作成され、fileを表します。
[FILEAPI]
resultを返します。
transferToImageBitmap()メソッドは、呼び出されると、次のステップを実行する必要があります。
このOffscreenCanvasオブジェクトの[[Detached]]内部スロットの値がtrueに設定されている場合、"InvalidStateError"を発生させます。
DOMException。
このOffscreenCanvasオブジェクトのコンテキストモードがnoneに設定されている場合、"InvalidStateError"を発生させます。DOMException。
新しく作成されたImageBitmapオブジェクトをimageに設定し、このOffscreenCanvasオブジェクトのビットマップを参照します。
このOffscreenCanvasオブジェクトのビットマップを新しく作成されたビットマップに設定し、以前のビットマップと同じ寸法とカラースペースを持つものにし、そのピクセルを透明な黒、またはレンダリングコンテキストのalphaフラグがfalseに設定されている場合は不透明な黒に初期化します。
これは、このOffscreenCanvasのレンダリングコンテキストがWebGLRenderingContextの場合、preserveDrawingBufferの値が影響を与えないことを意味します。
[WEBGL]
imageを返します。
次のものは、サポートが必要なイベントハンドラー(および対応するイベントハンドラーイベントタイプ)です。イベントハンドラーIDL属性として、OffscreenCanvasインターフェイスを実装するすべてのオブジェクトによってサポートされる必要があります。
| イベントハンドラー | イベントハンドラーイベントタイプ |
|---|---|
oncontextlost
| contextlost
|
oncontextrestored
| contextrestored
|
OffscreenCanvasRenderingContext2D
すべての現在のエンジンでサポートされています。
[Exposed =(Window ,Worker )]
interface OffscreenCanvasRenderingContext2D {
readonly attribute OffscreenCanvas canvas ;
};
OffscreenCanvasRenderingContext2D includes CanvasState ;
OffscreenCanvasRenderingContext2D includes CanvasTransform ;
OffscreenCanvasRenderingContext2D includes CanvasCompositing ;
OffscreenCanvasRenderingContext2D includes CanvasImageSmoothing ;
OffscreenCanvasRenderingContext2D includes CanvasFillStrokeStyles ;
OffscreenCanvasRenderingContext2D includes CanvasShadowStyles ;
OffscreenCanvasRenderingContext2D includes CanvasFilters ;
OffscreenCanvasRenderingContext2D includes CanvasRect ;
OffscreenCanvasRenderingContext2D includes CanvasDrawPath ;
OffscreenCanvasRenderingContext2D includes CanvasText ;
OffscreenCanvasRenderingContext2D includes CanvasDrawImage ;
OffscreenCanvasRenderingContext2D includes CanvasImageData ;
OffscreenCanvasRenderingContext2D includes CanvasPathDrawingStyles ;
OffscreenCanvasRenderingContext2D includes CanvasTextDrawingStyles ;
OffscreenCanvasRenderingContext2D includes CanvasPath ;
OffscreenCanvasRenderingContext2D
オブジェクトは、ビットマップに描画するためのレンダリングコンテキストです。これは、OffscreenCanvas
オブジェクトのものであり、CanvasRenderingContext2D
オブジェクトと似ていますが、以下の違いがあります:
ユーザーインターフェース 機能がサポートされていない。
その canvas
属性は、OffscreenCanvas
オブジェクトを参照し、canvas
エレメントではありません。
OffscreenCanvasRenderingContext2D
オブジェクトには、作成時に初期化される ビットマップ があります。
この ビットマップ には、true または false に設定できる origin-clean フラグがあります。最初にビットマップが作成されたとき、その origin-clean フラグは true に設定される必要があります。
OffscreenCanvasRenderingContext2D
オブジェクトには、true または false に設定できる alpha フラグもあります。コンテキストが作成されたとき、alpha フラグは
true に設定される必要があります。OffscreenCanvasRenderingContext2D
オブジェクトの alpha フラグが false に設定されている場合、その alpha
チャンネルはすべてのピクセルに対して 1.0(完全に不透明)に固定され、任意のピクセルの alpha 成分を変更しようとする試みは静かに無視される必要があります。
OffscreenCanvasRenderingContext2D
オブジェクトには、カラースペース 設定もあり、そのタイプは PredefinedColorSpace
です。コンテキストの ビットマップ のカラースペースは、コンテキストの カラースペース に設定されます。
OffscreenCanvasRenderingContext2D
オブジェクトには、関連する OffscreenCanvas オブジェクト もあり、これは OffscreenCanvas
オブジェクトです。このオブジェクトから OffscreenCanvasRenderingContext2D
オブジェクトが作成されました。
offscreenCanvas = offscreenCanvasRenderingContext2D.canvas
オフスクリーン 2D コンテキスト作成アルゴリズムは、target ( OffscreenCanvas
オブジェクト) およびオプションの引数を渡され、次の手順を実行します:
アルゴリズムがいくつかの引数を受け取った場合は、arg を最初の引数とします。そうでなければ、arg を undefined とします。
settings を 変換
の結果に設定し、arg を辞書型 CanvasRenderingContext2DSettings
にします。(これにより例外が発生する可能性があります)。
context を新しい OffscreenCanvasRenderingContext2D
オブジェクトに設定します。
context の 関連する
OffscreenCanvas オブジェクト を target に設定します。
もし settings["alpha"]
が false であれば、context の alpha フラグを false に設定します。
context の カラースペース を
settings["colorSpace"]
に設定します。
context の ビットマップ
を、新しく作成されたビットマップに設定し、幅
および 高さ
属性に基づいて target に設定します。target のビットマップも同じビットマップに設定します(共有されるようにします)。
もし context の alpha フラグが true に設定されている場合、context の ビットマップ のすべてのピクセルを 透明な黒 に初期化します。そうでなければ、ピクセルを 不透明な黒 に初期化します。
context を返します。
実装は、ウィンドウイベントループ のグラフィックス更新手順を短絡させ、プレースホルダー
キャンバス エレメント の内容を表示に更新するためのショートカットを提供することが推奨されます。これにより、たとえば、ビットマップの内容が プレースホルダー キャンバス エレメント
の物理的な表示位置にマッピングされたグラフィックスバッファに直接コピーされることがあります。このような短絡アプローチは、特に OffscreenCanvas
が ワーカーループ から更新され、ウィンドウイベントループ がビジー状態の
プレースホルダー キャンバス エレメント
において、表示遅延を大幅に削減することができます。ただし、そのようなショートカットには、スクリプトによって観測可能な副作用があってはなりません。これは、ビットマップが プレースホルダー キャンバス エレメント
に送信される必要があるためです。エレメントが CanvasImageSource
や ImageBitmapSource
として使用される場合、または toDataURL()
や toBlob()
が呼び出される場合に備えて、ビットマップを送信する必要があります。
canvas
属性は、取得時に、この OffscreenCanvasRenderingContext2D
の 関連する OffscreenCanvas
オブジェクト を返す必要があります。
キャンバス API
は、キャンバスのバッキングストアの色空間を指定するためのメカニズムを提供します。すべてのキャンバス API のデフォルトのバッキングストアの色空間は 'srgb' です。
キャンバスを出力デバイスにレンダリングする際、キャンバスのバッキングストアに色空間変換を適用する必要があります。この色空間変換は、色プロファイルがキャンバスのバッキングストアと同じ色空間を指定しているimg要素に適用される色空間変換と同一でなければなりません。
2D コンテキストにコンテンツを描画する際、すべての入力は描画前にコンテキストの色空間に変換されなければなりません。グラデーションのカラーストップの補間は、コンテキストの色空間に変換された後の色値に対して行われなければなりません。アルファブレンディングは、コンテキストの色空間に変換された後の値に対して行われなければなりません。
2D コンテキストに対する入力で、色空間が未定義のものは存在しません。CSS の色の色空間はCSS Colorで定義されています。色プロファイル情報を指定していない画像の色空間は、'srgb'であると想定されます。これは、CSS Colorのタグ付けされていない色の色空間セクションで指定されています。[CSSCOLOR]
ユーザーエージェントがtypeとオプションのqualityを指定して、ビットマップをファイルとしてシリアル化するときは、typeで指定された形式で画像ファイルを作成しなければなりません。画像ファイルの作成中にエラーが発生した場合(例:内部エンコーダーエラーなど)、シリアル化の結果はnullとなります。[PNG]
画像ファイルのピクセルデータは、ビットマップのピクセルデータを1座標空間単位あたり1画像ピクセルにスケーリングしたものでなければなりません。また、使用するファイル形式が解像度メタデータのエンコードをサポートしている場合、解像度は96dpi(1画像ピクセルあたりCSSピクセル)として指定しなければなりません。
typeが指定された場合、それは使用する形式を示すMIMEタイプとして解釈されなければなりません。タイプにパラメーターがある場合、それはサポートされていないものとして扱われなければなりません。
例えば、"image/png"という値はPNG画像を生成することを意味し、"image/jpeg"という値はJPEG画像を生成することを意味します。"image/svg+xml"という値はSVG画像を生成することを意味し(これはビットマップが生成された方法を追跡することをユーザーエージェントに要求し、実現は難しいですが可能性がある機能です)、おそらく非常に素晴らしい機能となるでしょう。
ユーザーエージェントはPNG ("image/png")
をサポートしなければなりません。ユーザーエージェントは他のタイプをサポートしてもよいです。ユーザーエージェントが要求されたタイプをサポートしていない場合は、PNG形式を使用してファイルを作成しなければなりません。[PNG]
ユーザーエージェントは、指定されたタイプをサポートするかどうかを確認する前に、指定されたタイプをASCII小文字に変換しなければなりません。
アルファチャンネルをサポートしていない画像タイプの場合、シリアル化された画像は、ビットマップ画像を不透明な黒の背景に合成し、source-over合成オペレーターを使用して作成しなければなりません。
色プロファイルをサポートする画像タイプの場合、シリアル化された画像には、基になるビットマップの色空間を示す色プロファイルを含めなければなりません。色プロファイルをサポートしていない画像タイプの場合、シリアル化された画像は、'srgb'色空間に'相対色度測定法'レンダリング意図を使用して変換しなければなりません。
したがって、2D コンテキストでは、drawImage()
メソッドを使用して toDataURL()
または toBlob()
メソッドの出力をキャンバスにレンダリングする場合、適切な寸法を指定すると、キャンバスの色がより狭いガマットにクリッピングされることを除けば、目に見える効果はありません。
typeが可変品質をサポートする画像形式(例:" image/jpeg")であり、qualityが指定され、typeが"image/png"ではない場合、Type(quality)がNumberであり、qualityが0.0から1.0の範囲にある場合、ユーザーエージェントはqualityを希望する品質レベルとして扱わなければなりません。そうでない場合、ユーザーエージェントは、quality引数が指定されなかったかのように、デフォルトの品質値を使用しなければなりません。
ここでのタイプテストの使用は、単にqualityをWeb IDLのdoubleとして宣言する代わりに、歴史的なアーティファクトです。
"品質"の解釈は、異なる実装によって若干異なる場合があります。品質が指定されていない場合は、圧縮率、画像品質、エンコード時間の間で合理的な妥協を表す実装固有のデフォルトが使用されます。
Canvas要素のセキュリティこのセクションは規範的ではありません。
情報漏洩は、1つのオリジンのスクリプトが、別のオリジン(同一オリジンではない)からの画像情報(例:ピクセルの読み取り)にアクセスできる場合に発生する可能性があります。
これを緩和するために、Canvas要素、OffscreenCanvasオブジェクト、およびImageBitmapオブジェクトに使用されるビットマップには、それらがオリジンクリーンであるかどうかを示すフラグが定義されています。すべてのビットマップは、そのオリジンクリーンがtrueに設定された状態で開始されます。このフラグは、クロスオリジンの画像が使用されたときにfalseに設定されます。
toDataURL()、toBlob()、およびgetImageData()メソッドはこのフラグをチェックし、クロスオリジンデータが漏洩しないように"SecurityError" DOMExceptionをスローします。
オリジンクリーンフラグの値は、createImageBitmap()によって、ソースのビットマップから新しいImageBitmapオブジェクトに伝播されます。逆に、ソース画像がオリジンクリーンフラグがfalseに設定されたImageBitmapオブジェクトである場合、drawImageによって、キャンバス要素のビットマップのオリジンクリーンフラグがfalseに設定されます。
このフラグは、特定の状況でリセットされることがあります。例えば、widthまたはheight属性を変更すると、ビットマップがクリアされ、オリジンクリーンフラグがリセットされます。
ImageBitmapRenderingContextを使用する場合、オリジンクリーンフラグの値は、ImageBitmapオブジェクトからキャンバスへと伝播されます。
プリマルチプライドアルファは、画像の透明性を表現する方法の1つであり、もう1つは非プリマルチプライドアルファです。
非プリマルチプライドアルファでは、ピクセルの赤、緑、および青のチャンネルがそのピクセルの色を表し、アルファチャンネルがそのピクセルの不透明度を表します。
一方、プリマルチプライドアルファでは、ピクセルの赤、緑、および青のチャンネルは、ピクセルが画像に追加する色の量を表し、アルファチャンネルは、ピクセルが背後のものを覆い隠す量を表します。
たとえば、色チャンネルが0(オフ)から255(最大強度)までの範囲であると仮定すると、次のように色が表現されます:
| CSS色表現 | プリマルチプライド表現 | 非プリマルチプライド表現 | 色の説明 | 他のコンテンツ上にブレンドされた色の画像 |
|---|---|---|---|---|
| rgba(255, 127, 0, 1) | 255, 127, 0, 255 | 255, 127, 0, 255 | 完全に不透明なオレンジ |
|
| rgba(255, 255, 0, 0.5) | 127, 127, 0, 127 | 255, 255, 0, 127 | 半透明の黄色 |
|
| 表現不可 | 255, 127, 0, 127 | 表現不可 | 加算半透明のオレンジ |
|
| 表現不可 | 255, 127, 0, 0 | 表現不可 | 加算完全透明なオレンジ |
|
| rgba(255, 127, 0, 0) | 0, 0, 0, 0 | 255, 127, 0, 0 | 完全に透明な(「見えない」)オレンジ |
|
| rgba(0, 127, 255, 0) | 0, 0, 0, 0 | 255, 127, 0, 0 | 完全に透明な(「見えない」)ターコイズ |
|
非プリマルチプライド表現からプリマルチプライド表現への色値の変換は、色の赤、緑、および青のチャンネルをそのアルファチャンネルで乗算することを含みます(「完全に透明」が0で、「完全に不透明」が1になるようにアルファチャンネルの範囲を再マッピングします)。
プリマルチプライド表現から非プリマルチプライド表現への色値の変換は、その逆であり、色の赤、緑、および青のチャンネルをアルファチャンネルで除算します。
特定の色はプリマルチプライドアルファでしか表現できず(例えば、加算色)、他の色は非プリマルチプライドアルファでしか表現できません(例えば、特定の赤、緑、および青の値を保持していても不透明度がない「見えない」色)。また、8ビット整数での除算および乗算(キャンバスの色が現在格納されている形式)が精度の低下を伴うため、プリマルチプライドアルファと非プリマルチプライドアルファの間の変換は、完全に不透明でない色に対しては情報が失われる操作です。
CanvasRenderingContext2Dの出力ビットマップおよびOffscreenCanvasRenderingContext2Dのビットマップは、透明色を表現するためにプリマルチプライドアルファを使用する必要があります。
キャンバスのビットマップがプリマルチプライドアルファを使用して色を表現することは、表現可能な色の範囲に影響を与えるため重要です。加算色は、CSS色が非プリマルチプライドであり、それらを表現できないため、現在キャンバスに直接描画することはできませんが、WebGLキャンバスに加算色を描画し、そのWebGLキャンバスをdrawImage()を介して2Dキャンバスに描画することは可能です。
すべての現行エンジンでサポートされています。
このセクションは規範的ではありません。
カスタム要素は、著者が独自の完全な機能を持つDOM要素を構築する方法を提供します。著者は常に非標準の要素を文書内で使用し、スクリプトや類似の方法でアプリケーション固有の動作を追加することができましたが、そのような要素は歴史的に非準拠であり、あまり機能的ではありませんでした。カスタム要素を定義することによって、著者はパーサーに要素を適切に構築する方法と、そのクラスの要素が変更にどのように反応するべきかを知らせることができます。
カスタム要素は、「プラットフォームの合理化」の一環として、既存のプラットフォーム機能(HTMLの要素など)を、カスタム要素の定義のような低レベルの著者が利用できる拡張ポイントに基づいて説明することを目的としています。今日では、カスタム要素の機能的および意味的な制限が多く存在し、それがHTMLの既存要素の動作を完全に説明することを妨げていますが、将来的にはこのギャップを縮小することを目指しています。
このセクションは規範的ではありません。
独立したカスタム要素を作成する方法を説明するために、小さな国旗アイコンをレンダリングするカスタム要素を定義しましょう。目標は、このように使えるようにすることです:
< flag-icon country = "nl" ></ flag-icon >
これを実現するために、まずカスタム要素のクラスを宣言し、HTMLElementを拡張します:
class FlagIcon extends HTMLElement {
constructor() {
super ();
this . _countryCode = null ;
}
static observedAttributes = [ "country" ];
attributeChangedCallback( name, oldValue, newValue) {
// nameは常に"country"になります observedAttributesのため
this . _countryCode = newValue;
this . _updateRendering();
}
connectedCallback() {
this . _updateRendering();
}
get country() {
return this . _countryCode;
}
set country( v) {
this . setAttribute( "country" , v);
}
_updateRendering() {
// これは読者の練習問題として残しておきますが、
// this.ownerDocument.defaultViewを確認して
// 閲覧コンテキストを持つドキュメントに挿入されたかどうかを確認し、
// そうでなければ作業を行わないようにしてください。
}
}
次に、このクラスを使用して要素を定義する必要があります:
customElements. define( "flag-icon" , FlagIcon);
ここまでで、上記のコードは機能するようになります!パーサーはflag-iconタグを見るたびに、新しいFlagIconクラスのインスタンスを構築し、country属性についてコードに通知します。これにより、要素の内部状態を設定し、適切なタイミングでレンダリングを更新します。
また、DOM APIを使用してflag-icon要素を作成することもできます:
const flagIcon = document. createElement( "flag-icon" )
flagIcon. country = "jp"
document. body. appendChild( flagIcon)
最後に、カスタム要素のコンストラクタ自体も使用できます。つまり、上記のコードは次のコードと同等です:
const flagIcon = new FlagIcon()
flagIcon. country = "jp"
document. body. appendChild( flagIcon)
このセクションは規範的ではありません。
静的な formAssociated プロパティに true の値を設定することで、独立型カスタム要素を フォームに関連するカスタム要素 に変えることができます。ElementInternals
インターフェイスは、フォームコントロール要素に共通する機能やプロパティを実装するのに役立ちます。
class MyCheckbox extends HTMLElement {
static formAssociated = true ;
static observedAttributes = [ 'checked' ];
constructor() {
super ();
this . _internals = this . attachInternals();
this . addEventListener( 'click' , this . _onClick. bind( this ));
}
get form() { return this . _internals. form; }
get name() { return this . getAttribute( 'name' ); }
get type() { return this . localName; }
get checked() { return this . hasAttribute( 'checked' ); }
set checked( flag) { this . toggleAttribute( 'checked' , Boolean( flag)); }
attributeChangedCallback( name, oldValue, newValue) {
// name は observedAttributes によって常に "checked" になります
this . _internals. setFormValue( this . checked ? 'on' : null );
}
_onClick( event) {
this . checked = ! this . checked;
}
}
customElements. define( 'my-checkbox' , MyCheckbox);
カスタム要素 my-checkbox は、組み込みのフォームに関連する要素のように使用できます。例えば、フォーム または ラベル
に配置することで、my-checkbox 要素をそれらに関連付けることができ、フォーム
を送信すると、my-checkbox 実装によって提供されるデータが送信されます。
< form action = "..." method = "..." >
< label >< my-checkbox name = "agreed" ></ my-checkbox > 規約を読みました。</ label >
< input type = "submit" >
</ form >
このセクションは規範的ではありません。
ElementInternals
の適切なプロパティを使用することで、カスタム要素にデフォルトのアクセシビリティセマンティクスを持たせることができます。次のコードは、前のセクションで紹介したフォームに関連するチェックボックスを拡張し、アクセシビリティ技術によって見られるデフォルトのロールとチェック状態を適切に設定します:
class MyCheckbox extends HTMLElement {
static formAssociated = true ;
static observedAttributes = [ 'checked' ];
constructor() {
super ();
this . _internals = this . attachInternals();
this . addEventListener( 'click' , this . _onClick. bind( this ));
this . _internals. role = 'checkbox' ;
this . _internals. ariaChecked = 'false' ;
}
get form() { return this . _internals. form; }
get name() { return this . getAttribute( 'name' ); }
get type() { return this . localName; }
get checked() { return this . hasAttribute( 'checked' ); }
set checked( flag) { this . toggleAttribute( 'checked' , Boolean( flag)); }
attributeChangedCallback( name, oldValue, newValue) {
// 観察属性によって、nameは常に「checked」になります
this . _internals. setFormValue( this . checked ? 'on' : null );
this . _internals. ariaChecked = this . checked;
}
_onClick( event) {
this . checked = ! this . checked;
}
}
customElements. define( 'my-checkbox' , MyCheckbox);
ビルトイン要素と同様に、これらはデフォルトの設定であり、ページ作成者が role や aria-*
属性を使用して上書きすることができます:
<!-- このマークアップは非準拠です -->
< input type = "checkbox" checked role = "button" aria-checked = "false" >
<!-- このマークアップはおそらくカスタム要素の作成者が意図したものではありません -->
< my-checkbox role = "button" checked aria-checked = "false" >
カスタム要素の作成者は、アクセシビリティセマンティクスのどの側面が強力なネイティブセマンティクスであり、カスタム要素のユーザーによって上書きされるべきでないかを明示することが推奨されます。例として、my-checkbox
要素の作成者は、その role と aria-checked
の値が強力なネイティブセマンティクスであると述べ、上記のようなコードを避けることを促します。
このセクションは規範的ではありません。
カスタマイズされたビルトイン要素は、カスタム要素の一種であり、自律カスタム要素とは異なり、若干異なる方法で定義され、非常に異なる方法で使用されます。これらは、既存のHTML要素の動作を再利用し、それに新しいカスタム機能を追加するために存在します。これは、HTML要素の既存の動作の多くが、純粋に自律カスタム要素を使用して複製することができないという現実に対処するために重要です。代わりに、カスタマイズされたビルトイン要素は、既存の要素にカスタムの構築動作、ライフサイクルフック、およびプロトタイプチェーンをインストールし、これらの機能を既存の要素に「ミックスイン」することができます。
カスタマイズされたビルトイン要素には、自律カスタム要素とは異なる構文が必要です。これは、ユーザーエージェントや他のソフトウェアが要素のローカル名を基にして、その要素のセマンティクスや動作を識別するためです。つまり、カスタマイズされたビルトイン要素が既存の動作の上に構築されるという概念は、拡張された要素が元のローカル名を保持することに依存しています。
この例では、カスタマイズされたビルトイン要素であるplastic-buttonを作成します。これは通常のボタンのように動作しますが、クリックするたびに派手なアニメーション効果が追加されます。まずクラスを定義しますが、今回はHTMLButtonElementではなく、HTMLElementを拡張します:
class PlasticButton extends HTMLButtonElement {
constructor() {
super ();
this . addEventListener( "click" , () => {
// 派手なアニメーション効果を描画します!
});
}
}
カスタム要素を定義する際には、extendsオプションを指定する必要があります:
customElements. define( "plastic-button" , PlasticButton, { extends : "button" });
一般的に、拡張される要素の名前は、どの要素インターフェースを拡張しているかを見ただけでは決定できません。例えば、qとblockquoteの両方がHTMLQuoteElementを共有しているように、多くの要素が同じインターフェースを共有しています。
解析されたHTMLソーステキストからカスタマイズされたビルトイン要素を構築するには、is属性をbutton要素に使用します:
< button is = "plastic-button" > Click Me!</ button >
カスタマイズされたビルトイン要素を自律カスタム要素として使用しようとしても、うまくいきません。つまり、<plastic-button>Click me?</plastic-button>は、特別な動作のないHTMLElementを単に作成するだけです。
プログラムによってカスタマイズされたビルトイン要素を作成する必要がある場合は、次の形式のcreateElement()を使用できます:
const plasticButton = document. createElement( "button" , { is: "plastic-button" });
plasticButton. textContent = "Click me!" ;
そして、前と同じように、コンストラクタも機能します:
const plasticButton2 = new PlasticButton();
console. log( plasticButton2. localName); // 「button」と出力されます
console. assert( plasticButton2 instanceof PlasticButton);
console. assert( plasticButton2 instanceof HTMLButtonElement);
プログラムによってカスタマイズされたビルトイン要素を作成する場合、is属性はDOMには存在しませんが、明示的に設定されていないためです。しかし、シリアル化時に出力に追加されます:
console. assert( ! plasticButton. hasAttribute( "is" ));
console. log( plasticButton. outerHTML); // 「<button is="plastic-button"></button>」と出力されます
作成方法に関係なく、buttonに特有のすべての方法は、このような「plastic
buttons」にも適用されます。それらのフォーカス動作、フォーム送信への参加能力、無効属性などです。
カスタマイズされたビルトイン要素は、ユーザーエージェントによって提供される有用な動作やAPIを持つ既存のHTML要素を拡張することを目的としています。そのため、bgsound、blink、isindex、keygen、multicol、nextid、またはspacerなどのレガシー要素を拡張することはできません。これらはHTMLUnknownElementを要素インターフェースとして使用するように定義されています。
この要件の理由の1つは、将来の互換性です。たとえば、現在未知の要素であるcomboboxを拡張するカスタマイズされたビルトイン要素が定義されている場合、この仕様書が将来combobox要素を定義するのを妨げることになります。なぜなら、カスタマイズされたビルトイン要素の派生物の消費者は、基本要素が面白いユーザーエージェント提供の動作を持たないことに依存してしまうからです。
このセクションは規範的ではありません。
以下に指定されているように、また上記で言及されたように、単にtaco-buttonという要素を定義して使用することは、その要素がボタンを表していることを意味しません。つまり、ウェブブラウザー、検索エンジン、アクセシビリティ技術などのツールは、定義された名前に基づいて自動的にその要素をボタンとして扱うわけではありません。
依然として自律カスタム要素を使用しながら、さまざまなユーザーにボタンのセマンティクスを伝えるためには、いくつかの技術を用いる必要があります:
tabindex属性を追加することで、taco-buttonをフォーカス可能にできます。ただし、taco-buttonが論理的に無効になった場合、このtabindex属性を削除する必要があります。
ARIAの役割やさまざまなARIA状態とプロパティを追加することで、アクセシビリティ技術にセマンティクスを伝えることができます。たとえば、roleを「button」に設定することで、これがボタンであることを伝え、ユーザーがアクセシビリティ技術で通常のボタンのような操作でこのコントロールを操作できるようにします。また、aria-labelプロパティを設定することで、アクセシビリティ技術が子テキストノードをたどってそれらを発表する代わりに、ボタンにアクセス可能な名前を与えることができます。そして、ボタンが論理的に無効になったときに、aria-disabled状態を「true」に設定することで、アクセシビリティ技術にボタンの無効状態を伝えることができます。
一般的に期待されるボタンの動作を処理するためにイベントハンドラを追加することで、ウェブブラウザーのユーザーにボタンのセマンティクスを伝えることができます。この場合、最も関連するイベントハンドラは、適切なkeydownイベントをclickイベントにプロキシするもので、キーボードおよびクリックによってボタンをアクティブにできるようにします。
taco-button要素に提供されるデフォルトの視覚的スタイリングに加えて、論理的な状態の変化を反映するために視覚的スタイリングも更新する必要があります。たとえば、無効になるといった状態です。つまり、taco-buttonのスタイルシートにルールがある場合、taco-button[disabled]に対してもルールが必要になります。
これらの点を考慮して、ボタンのセマンティクス(無効にする機能を含む)を伝える責任を負う完全機能のtaco-buttonは、次のようなものになるかもしれません:
class TacoButton extends HTMLElement {
static observedAttributes = [ "disabled" ];
constructor() {
super ();
this . _internals = this . attachInternals();
this . _internals. role = "button" ;
this . addEventListener( "keydown" , e => {
if ( e. code === "Enter" || e. code === "Space" ) {
this . dispatchEvent( new PointerEvent( "click" , {
bubbles: true ,
cancelable: true
}));
}
});
this . addEventListener( "click" , e => {
if ( this . disabled) {
e. preventDefault();
e. stopImmediatePropagation();
}
});
this . _observer = new MutationObserver(() => {
this . _internals. ariaLabel = this . textContent;
});
}
connectedCallback() {
this . setAttribute( "tabindex" , "0" );
this . _observer. observe( this , {
childList: true ,
characterData: true ,
subtree: true
});
}
disconnectedCallback() {
this . _observer. disconnect();
}
get disabled() {
return this . hasAttribute( "disabled" );
}
set disabled( flag) {
this . toggleAttribute( "disabled" , Boolean( flag));
}
attributeChangedCallback( name, oldValue, newValue) {
// 名前は常に「disabled」になります(observedAttributesのため)
if ( this . disabled) {
this . removeAttribute( "tabindex" );
this . _internals. ariaDisabled = "true" ;
} else {
this . setAttribute( "tabindex" , "0" );
this . _internals. ariaDisabled = "false" ;
}
}
}
このように、かなり複雑な要素の定義であっても、その要素は消費者にとっては使いやすいとは言えません。自らの意思でtabindex属性を「生やし続ける」ことになり、tabindex="0"のフォーカス可能性の動作が現在のプラットフォームのbuttonの動作に合わない場合があります。これは、現時点ではカスタム要素に対してデフォルトのフォーカス動作を指定する方法がなく、tabindex属性を使用することが強制されるためです(通常は、消費者がデフォルトの動作をオーバーライドできるようにするために予約されているにもかかわらず)。
対照的に、前のセクションで示したようなシンプルなカスタマイズされたビルトイン要素は、button要素のセマンティクスと動作を自動的に継承し、これらの動作を手動で実装する必要がありません。一般に、HTMLの既存要素に基づいて構築された、非自明な動作とセマンティクスを持つ要素にとって、カスタマイズされたビルトイン要素は、開発、保守、消費がより簡単になります。
このセクションは規範的ではありません。
要素の定義はいつでも行うことができるため、カスタムでない要素が生成され、その後適切な定義が登録された後にカスタム要素になることがあります。このプロセスは、通常の要素をカスタム要素に「アップグレード」するものと呼ばれます。
アップグレードにより、たとえばパーサによって関連要素が最初に生成された後にカスタム要素定義を登録するのが好ましいシナリオを可能にします。これにより、カスタム要素のコンテンツを段階的に強化することができます。たとえば、次のHTMLドキュメントでは、img-viewer要素の定義が非同期で読み込まれます:
<!DOCTYPE html>
< html lang = "en" >
< title > Image viewer example</ title >
< img-viewer filter = "Kelvin" >
< img src = "images/tree.jpg" alt = "A beautiful tree towering over an empty savannah" >
</ img-viewer >
< script src = "js/elements/img-viewer.js" async ></ script >
ここでは、img-viewer要素の定義がscript要素を使用して非同期で読み込まれており、async属性が指定されており、マークアップ内の<img-viewer>タグの後に配置されています。スクリプトが読み込まれるまで、img-viewer要素は定義されていない要素として扱われ、spanと同様に処理されます。スクリプトが読み込まれると、img-viewer要素が定義され、ページ上の既存のimg-viewer要素がアップグレードされ、カスタム要素の定義が適用されます(おそらく、「Kelvin」という文字列で指定された画像フィルターを適用し、画像の視覚的な外観を強化します)。
アップグレードは、ドキュメントツリー内の要素にのみ適用されることに注意してください。(正式には、接続された要素。)ドキュメントに挿入されていない要素はアップグレードされません。次の例は、このポイントを説明しています:
<!DOCTYPE html>
< html lang = "en" >
< title > Upgrade edge-cases example</ title >
< example-element ></ example-element >
< script >
"use strict" ;
const inDocument = document. querySelector( "example-element" );
const outOfDocument = document. createElement( "example-element" );
// 要素の定義前は、どちらもHTMLElementです:
console. assert( inDocument instanceof HTMLElement);
console. assert( outOfDocument instanceof HTMLElement);
class ExampleElement extends HTMLElement {}
customElements. define( "example-element" , ExampleElement);
// 要素の定義後、ドキュメント内の要素はアップグレードされました:
console. assert( inDocument instanceof ExampleElement);
console. assert( ! ( outOfDocument instanceof ExampleElement));
document. body. appendChild( outOfDocument);
// ドキュメント内に移動したので、こちらもアップグレードされました:
console. assert( outOfDocument instanceof ExampleElement);
</ script >
ユーザーエージェントによって提供される組み込み要素には、ユーザーの操作やその他の要因に応じて時間とともに変化する特定の状態があり、疑似クラスを通じてウェブ作者に公開されています。例えば、いくつかのフォームコントロールには「invalid」状態があり、これは:invalid疑似クラスで公開されています。
組み込み要素と同様に、カスタム要素もさまざまな状態を持つことができ、カスタム要素の作者は、これらの状態を組み込み要素と同様の方法で公開したいと考えています。
これは:state()疑似クラスを介して行われます。カスタム要素の作者は、statesプロパティを使用して、ElementInternalsのカスタム状態を追加および削除し、それらが:state()疑似クラスの引数として公開されるようにします。
次の例は、:state()を使用してカスタムチェックボックス要素をスタイリングする方法を示しています。LabeledCheckboxが「checked」状態をコンテンツ属性で公開しないと仮定します。
< script >
class LabeledCheckbox extends HTMLElement {
constructor() {
super ();
this . _internals = this . attachInternals();
this . addEventListener( 'click' , this . _onClick. bind( this ));
const shadowRoot = this . attachShadow({ mode: 'closed' });
shadowRoot. innerHTML =
`<style>
:host::before {
content: '[ ]';
white-space: pre;
font-family: monospace;
}
:host(:state(checked))::before { content: '[x]' }
</style> `;
}
get checked() { return this . _internals. states. has( 'checked' ); }
set checked( flag) {
if ( flag)
this . _internals. states. add( 'checked' );
else
this . _internals. states. delete ( 'checked' );
}
_onClick( event) {
this . checked = ! this . checked;
}
}
customElements. define( 'labeled-checkbox' , LabeledCheckbox);
</ script >
< style >
labeled-checkbox { border : dashed red ; }
labeled-checkbox : state ( checked ) { border : solid ; }
</ style >
< labeled-checkbox > You need to check this</ labeled-checkbox >
カスタム疑似クラスはシャドウパーツをターゲットにすることもできます。上記の例を拡張したものがこれです:
< script >
class QuestionBox extends HTMLElement {
constructor() {
super ();
const shadowRoot = this . attachShadow({ mode: 'closed' });
shadowRoot. innerHTML =
`<div><slot>Question</slot></div>
<labeled-checkbox part='checkbox'>Yes</labeled-checkbox>` ;
}
}
customElements. define( 'question-box' , QuestionBox);
</ script >
< style >
question-box :: part ( checkbox ) { color : red ; }
question-box :: part ( checkbox ) : state ( checked ) { color : green ; }
</ style >
< question-box > Continue?</ question-box >
カスタム要素のコンストラクターを作成する際、著者は次の適合要件に従う必要があります。
パラメータなしのsuper()呼び出しは、コンストラクタ本体の最初の文でなければならず、適切なプロトタイプチェーンとthis値を確立してから、さらにコードを実行します。
return文は、単純な早期リターン(returnまたはreturn this)を除いて、コンストラクタ本体のどこにも表示されてはいけません。
コンストラクタは、document.write()やdocument.open()メソッドを使用してはいけません。
要素の属性や子要素は調査してはいけません。なぜなら、非アップグレードの場合にはそれらが存在しないためであり、アップグレードに依存することは要素の使いやすさを低下させるからです。
要素は、属性や子要素を追加してはいけません。これは、createElementやcreateElementNSメソッドを使用する消費者の期待を裏切ることになるからです。
一般的に、リソースの取得やレンダリングを含む作業は、可能な限りconnectedCallbackに延期する必要があります。ただし、connectedCallbackは複数回呼び出される可能性があるため、真に一度だけ行われる初期化作業には、それが2回実行されるのを防ぐためのガードが必要です。
一般的に、コンストラクタは初期状態やデフォルト値の設定、イベントリスナーの設定、および必要に応じてシャドウルートを設定するために使用されるべきです。
これらの要件のいくつかは、要素作成の過程で直接または間接的にチェックされ、それに従わないと、パーサーやDOM APIによってインスタンス化できないカスタム要素が作成されます。これは、マイクロタスク内で作業が行われた場合でも同様であり、マイクロタスクチェックポイントが構築直後に発生する可能性があるためです。
カスタム要素の反応を作成する際、著者はノードツリーの操作を避けるべきです。これにより予期しない結果が生じる可能性があるためです。
要素のconnectedCallbackが切断される前にキューに入れられることがありますが、コールバックキューがまだ処理されているため、接続されていない要素のconnectedCallbackが結果として生じることがあります:
class CParent extends HTMLElement {
connectedCallback() {
this . firstChild. remove();
}
}
customElements. define( "c-parent" , CParent);
class CChild extends HTMLElement {
connectedCallback() {
console. log( "CChild connectedCallback: isConnected =" , this . isConnected);
}
}
customElements. define( "c-child" , CChild);
const parent = new CParent(),
child = new CChild();
parent. append( child);
document. body. append( parent);
// Logs:
// CChild connectedCallback: isConnected = false
カスタム要素とは、カスタムされた要素です。非公式には、これはそのコンストラクタとプロトタイプがユーザーエージェントではなく、著者によって定義されることを意味します。この著者によって提供されたコンストラクタ関数は、カスタム要素コンストラクタと呼ばれます。
2つの異なる種類のカスタム要素を定義できます:
独立カスタム要素は、extendsオプションなしで定義されます。この種類のカスタム要素は、定義された名前と等しいローカル名を持ちます。
カスタマイズされた組み込み要素は、extendsオプションを使用して定義されます。この種類のカスタム要素は、extendsオプションに渡された値と等しいローカル名を持ち、その定義された名前がis属性の値として使用されます。そのため、これは有効なカスタム要素名でなければなりません。
カスタム要素が作成された後、is属性の値を変更しても、その要素の動作は変わりません。これは、要素のis値として保存されているためです。
独立カスタム要素は、次の要素定義を持ちます:
is属性を除くform、フォーム関連カスタム要素に対して—form要素に関連付けます。
disabled、フォーム関連カスタム要素に対して—フォームコントロールが無効であるかどうか。
readonly、フォーム関連カスタム要素に対して—willValidateに影響します。さらに、カスタム要素著者によって追加された動作。
name、フォーム関連カスタム要素に対して—フォーム送信およびform.elementsAPIで使用する要素の名前。
HTMLElementから継承される)独立カスタム要素には特別な意味はありません。それは子要素を表現します。カスタマイズされた組み込み要素は、それが拡張する要素のセマンティクスを継承します。
名前空間を持たない、要素の機能に関連するすべての属性は、要素の著者によって指定される限り、独立カスタム要素に指定できます。ただし、属性名がXML互換であり、ASCII大文字を含まない場合に限ります。例外はis属性であり、独立カスタム要素に指定してはいけません(指定しても効果はありません)。
カスタマイズされた組み込み要素は、拡張する要素に基づいて属性に関する通常の要件に従います。カスタムの属性ベースの動作を追加するには、data-*属性を使用します。
独立カスタム要素は、要素がカスタム要素定義に関連付けられていて、そのフォーム関連フィールドがtrueに設定されている場合、フォーム関連カスタム要素と呼ばれます。
name属性は、フォーム関連カスタム要素の名前を表します。disabled属性は、フォーム関連カスタム要素を非インタラクティブにし、その送信値が送信されるのを防ぐために使用されます。form属性は、フォーム関連カスタム要素をそのフォーム所有者と明示的に関連付けるために使用されます。
readonly属性は、フォーム関連カスタム要素の制約検証から除外されることを指定します。ユーザーエージェントは、この属性に対して他の動作を提供しませんが、カスタム要素の著者は、そのコントロールを内蔵フォームコントロールのreadonly属性の動作に似た適切な方法で編集不可にするために、この属性の存在を利用すべきです。
制約検証: readonly属性がフォーム関連カスタム要素に指定されている場合、その要素は制約検証から除外されます。
リセットアルゴリズムは、フォーム関連カスタム要素に対して、要素を指定してカスタム要素のコールバック反応をキューに入れることです。コールバック名は「formResetCallback」であり、引数リストは空です。
有効なカスタム要素名とは、以下のすべての要件を満たす文字列nameです:
nameは、PotentialCustomElementName生成規則に一致する必要があります:
PotentialCustomElementName ::=[a-z] (PCENChar)* '-' (PCENChar)*
PCENChar ::="-" | "." | [0-9] | "_" | [a-z] | #xB7 | [#xC0-#xD6] | [#xD8-#xF6] | [#xF8-#x37D] | [#x37F-#x1FFF] | [#x200C-#x200D] | [#x203F-#x2040] | [#x2070-#x218F] | [#x2C00-#x2FEF] | [#x3001-#xD7FF] | [#xF900-#xFDCF] | [#xFDF0-#xFFFD] | [#x10000-#xEFFFF]
nameは、次のいずれでもあってはなりません:
annotation-xmlcolor-profilefont-facefont-face-srcfont-face-urifont-face-formatfont-face-namemissing-glyph上記の名前のリストは、適用される仕様、つまりSVG 2およびMathMLからのハイフンを含む要素名の概要です。[SVG] [MATHML]
これらの要件は、有効なカスタム要素名のいくつかの目標を確保します:
それらはASCII小文字で始まり、HTMLパーサーがそれらをタグとして処理することを保証します。
それらはASCII大文字を含まないため、ユーザーエージェントがHTML要素を常にASCII大文字小文字無視で扱うことを保証します。
それらはハイフンを含み、名前空間の指定に使用され、将来的な互換性を確保します(ハイフンを含むローカル名を持つ要素がHTML、SVG、またはMathMLに追加されることはありません)。
それらは常にcreateElement()およびcreateElementNS()で作成できます。これらはパーサーの制限を超えた制約を持ちます。
これらの制限を除いて、<math-α>や<emotion-😍>のようなユースケースに最大の柔軟性を持たせるために、幅広い名前が許可されています。
カスタム要素定義とは、カスタム要素を説明し、以下で構成されるものです:
CustomElementConstructorコールバック関数タイプ値でカスタム要素コンストラクタをラップします。sequence<DOMString>connectedCallback"、"disconnectedCallback"、
"adoptedCallback"、
"attributeChangedCallback"、
"formAssociatedCallback"、
"formDisabledCallback"、
"formResetCallback"、
"formStateRestoreCallback"の文字列であるマップです。それに対応する値は、Web
IDLのFunctionコールバック関数タイプ値、またはnullです。デフォルトでは、各エントリの値はnullです。
attachInternals()を制御します。
attachShadow()を制御します。
カスタム要素定義を検索するためには、document、namespace、localName、およびisを指定して、以下の手順を実行します。これらの手順は、カスタム要素定義またはnullのいずれかを返します:
namespaceがHTML名前空間でない場合、nullを返します。
documentの閲覧コンテキストがnullの場合、nullを返します。
registryをdocumentの関連グローバルオブジェクトのCustomElementRegistryオブジェクトとして取得します。
registryにlocalNameと等しい名前およびローカル名を持つカスタム要素定義が存在する場合、そのカスタム要素定義を返します。
registryにisと等しい名前およびlocalNameと等しいローカル名を持つカスタム要素定義が存在する場合、そのカスタム要素定義を返します。
nullを返します。
CustomElementRegistryインターフェースすべての現在のエンジンでサポートされています。
各Windowオブジェクトは、CustomElementRegistryオブジェクトのユニークなインスタンスに関連付けられ、そのWindowオブジェクトが作成されたときに割り当てられます。
カスタム要素レジストリは、Documentオブジェクトではなく、Windowオブジェクトに関連付けられます。これは、各カスタム要素コンストラクタがHTMLElementインターフェースから継承されており、Windowオブジェクトごとに正確に1つのHTMLElementインターフェースが存在するためです。
すべての現在のエンジンでサポートされています。
customElements属性は、そのWindowオブジェクトのCustomElementRegistryオブジェクトを返さなければなりません。
[Exposed =Window ]
interface CustomElementRegistry {
[CEReactions ] undefined define (DOMString name , CustomElementConstructor constructor , optional ElementDefinitionOptions options = {});
(CustomElementConstructor or undefined ) get (DOMString name );
DOMString ? getName (CustomElementConstructor constructor );
Promise <CustomElementConstructor > whenDefined (DOMString name );
[CEReactions ] undefined upgrade (Node root );
};
callback CustomElementConstructor = HTMLElement ();
dictionary ElementDefinitionOptions {
DOMString extends ;
};
すべてのCustomElementRegistryには、初期状態では空のカスタム要素定義のセットが含まれています。一般的に、この仕様のアルゴリズムは、名前、ローカル名、またはコンストラクタのいずれかでレジストリ内の要素を検索します。
すべてのCustomElementRegistryには、要素定義の再入呼び出しを防ぐために使用される要素定義が実行中であるフラグも含まれています。このフラグは最初は未設定です。
すべてのCustomElementRegistryには、有効なカスタム要素名を約束にマッピングするwhen-defined プロミスマップも含まれています。これは、whenDefined()メソッドの実装に使用されます。
window.customElements.define(name, constructor)
すべての現在のエンジンでサポートされています。
window.customElements.define(name, constructor, { extends: baseLocalName })
NotSupportedError"のDOMExceptionが、カスタム要素や不明な要素を拡張しようとするとスローされます。
window.customElements.get(name)
すべての現在のエンジンでサポートされています。
window.customElements.getName(constructor)
window.customElements.whenDefined(name)
CustomElementRegistry/whenDefined
すべての現在のエンジンでサポートされています。
SyntaxError"のDOMExceptionで拒否されたプロミスを返します。
window.customElements.upgrade(root)
すべての現在のエンジンでサポートされています。
要素定義とは、カスタム要素定義をCustomElementRegistryに追加するプロセスです。これは、define()メソッドによって実行されます。このメソッドが呼び出されたとき、次のステップを実行する必要があります。
IsConstructor(constructor)がfalseの場合、TypeErrorをスローします。
nameが有効なカスタム要素名でない場合、"SyntaxError" DOMExceptionをスローします。
このCustomElementRegistryにnameがnameと一致するエントリが含まれている場合、"NotSupportedError" DOMExceptionをスローします。
このCustomElementRegistryにconstructorがconstructorと一致するエントリが含まれている場合、"NotSupportedError" DOMExceptionをスローします。
localNameをnameと設定します。
extendsをoptionsのextendsメンバーの値に設定します。該当するメンバーが存在しない場合はnullに設定します。
extendsがnullでない場合は、次の手順を実行します:
extendsが有効なカスタム要素名である場合、"NotSupportedError" DOMExceptionをスローします。
extendsのelement interfaceがhtml namespaceでHTMLUnknownElementの場合(例:
extendsがこの仕様の要素定義を示していない場合)、"NotSupportedError" DOMExceptionをスローします。
localNameをextendsに設定します。
このCustomElementRegistryのelement
definition is runningフラグが設定されている場合、"NotSupportedError" DOMExceptionをスローします。
このCustomElementRegistryのelement
definition is runningフラグを設定します。
formAssociatedをfalseに設定します。
disableInternalsをfalseに設定します。
disableShadowをfalseに設定します。
observedAttributesを空のsequence<DOMString>に設定します。
例外をキャッチしながら、次のサブステップを実行します:
prototypeを? Get(constructor, "prototype")で取得します。
lifecycleCallbacksというマップを作成し、キーとして"connectedCallback"、"disconnectedCallback"、"adoptedCallback"、および"attributeChangedCallback"を設定し、それぞれのエントリの値をnullにします。
前のステップでリストした順に、lifecycleCallbacks内の各キーcallbackNameに対して:
"attributeChangedCallback"というキーを持つlifecycleCallbacksのエントリの値がnullでない場合:
observedAttributesIterableを? Get(constructor, "observedAttributes")で取得します。
observedAttributesIterableがundefinedでない場合、observedAttributesをobservedAttributesIterableをsequence<DOMString>に変換した結果に設定します。変換時に例外が発生した場合は、その例外を再スローします。
disabledFeaturesを空のsequence<DOMString>に設定します。
disabledFeaturesIterableを? Get(constructor, "disabledFeatures")で取得します。
disabledFeaturesIterableがundefinedでない場合、disabledFeaturesをdisabledFeaturesIterableをsequence<DOMString>に変換した結果に設定します。変換時に例外が発生した場合は、その例外を再スローします。
disabledFeaturesが"internals"を含む場合、disableInternalsをtrueに設定します。
disabledFeaturesが"shadow"を含む場合、disableShadowをtrueに設定します。
formAssociatedValueを? Get(constructor, "formAssociated")で取得します。
formAssociatedをformAssociatedValueをbooleanに変換した結果に設定します。変換時に例外が発生した場合は、その例外を再スローします。
もしformAssociatedがtrueであれば、"formAssociatedCallback"、"formResetCallback"、"formDisabledCallback"、および"formStateRestoreCallback"の各callbackNameに対して:
次に、上記のステップが例外をスローしたかどうかに関わらず、以下のサブステップを実行します:
このCustomElementRegistryのelement definition is
runningフラグを解除します。
最終的に、最初のサブステップで例外がスローされた場合、その例外を再スローします(これによりこのアルゴリズムは終了します)。そうでない場合は、次に進みます。
definitionを新しいカスタム要素定義として作成し、name、localName、constructor、observedAttributes、lifecycleCallbacks、formAssociated、disableInternals、およびdisableShadowの値をそれぞれ設定します。
definitionをこのCustomElementRegistryに追加します。
documentをこのCustomElementRegistryの関連するグローバルオブジェクトの関連するDocumentとして設定します。
upgrade candidatesを、documentのシャドウ含む子孫であり、html
namespace内のlocalNameと一致するすべての要素として設定します。さらに、extendsがnullでない場合は、is値がnameと一致する要素のみを含めます。
各upgrade candidatesのelementに対して、カスタム要素アップグレード反応をキューに追加し、elementおよびdefinitionを指定します。
このCustomElementRegistryのwhen-definedプロミスマップにキーnameのエントリが含まれている場合:
promiseをそのエントリの値として設定します。
promiseをconstructorで解決します。
このCustomElementRegistryのwhen-definedプロミスマップからキーnameのエントリを削除します。
呼び出された際、get(name)メソッドは以下のステップを実行する必要があります:
このCustomElementRegistryがnameという名前を持つエントリを含んでいる場合、そのエントリのコンストラクタを返します。
それ以外の場合、undefinedを返します。
getName(constructor)メソッドは、以下のステップを実行する必要があります:
このCustomElementRegistryがconstructorというコンストラクタを持つエントリを含んでいる場合、そのエントリの名前を返します。
それ以外の場合、nullを返します。
呼び出された際、whenDefined(name)メソッドは、以下のステップを実行する必要があります:
もしnameが有効なカスタム要素名ではない場合、拒否された約束を"SyntaxError"と共に返します。
このCustomElementRegistryがnameという名前を持つエントリを含んでいる場合、そのエントリのコンストラクタで解決された約束を返します。
mapを、このCustomElementRegistryのwhen-defined
約束マップに設定します。
mapがキーnameを持つエントリを含んでいない場合、mapにキーnameと新しい約束を持つエントリを作成します。
promiseを、キーnameを持つmapのエントリの値に設定します。
promiseを返します。
whenDefined()メソッドは、適切なカスタム要素が定義されるまでアクションの実行を避けるために使用できます。この例では、:defined疑似クラスと組み合わせて、使用されるすべての自律カスタム要素が定義されるまで、動的に読み込まれる記事の内容を非表示にします。
articleContainer. hidden = true ;
fetch( articleURL)
. then( response => response. text())
. then( text => {
articleContainer. innerHTML = text;
return Promise. all(
[... articleContainer. querySelectorAll( ":not(:defined)" )]
. map( el => customElements. whenDefined( el. localName))
);
})
. then(() => {
articleContainer. hidden = false ;
});
呼び出された際、upgrade(root)メソッドは以下のステップを実行する必要があります:
candidatesをrootのシャドウを含むすべての包含子孫要素のシャドウを含む木の順序で並べたリストに設定します。
各 candidatesのcandidateに対して、アップグレードを試みます。
upgrade()メソッドは、要素を任意にアップグレードすることを可能にします。通常、要素は接続されると自動的にアップグレードされますが、このメソッドは要素を接続する準備ができる前にアップグレードする必要がある場合に使用できます。
const el = document. createElement( "spider-man" );
class SpiderMan extends HTMLElement {}
customElements. define( "spider-man" , SpiderMan);
console. assert( ! ( el instanceof SpiderMan)); // not yet upgraded
customElements. upgrade( el);
console. assert( el instanceof SpiderMan); // upgraded!
definitionと要素elementを入力として与えられた場合、要素をアップグレードするために、次の手順を実行します:
elementのカスタム要素状態が「undefined」または「uncustomized」でない場合は、処理を終了します。
これは、このアルゴリズムが再入可能な呼び出しにより発生する場合があります。例えば、次のような例があります:
<!DOCTYPE html>
< x-foo id = "a" ></ x-foo >
< x-foo id = "b" ></ x-foo >
< script >
// 定義は、「a」と「b」の両方に対してアップグレードのリアクションをキューに追加します
customElements. define( "x-foo" , class extends HTMLElement {
constructor() {
super ();
const b = document. querySelector( "#b" );
b. remove();
// このコンストラクタが「a」のために実行されている間、「b」はまだ
// undefined であるため、ドキュメントに挿入すると、
// x-foo を定義することによってキューに追加されたものとは別に、「b」のための二番目のアップグレードリアクションがキューに追加されます。
document. body. appendChild( b);
}
})
</ script >
この手順により、「b」が二度目に呼び出された際に、要素のアップグレードが早期にアルゴリズムを終了します。
elementのカスタム要素定義をdefinitionに設定します。
elementのカスタム要素状態を「failed」に設定します。
アップグレードが成功した後に「custom」に設定されます。現在のところ、「failed」に設定することで、再入可能な呼び出しが上記の早期終了ステップに到達するようになります。
順番にelementの属性リスト内の属性ごとに、element、コールバック名「attributeChangedCallback」および、属性のローカル名、null、属性の値、属性の名前空間を含む引数リストを用いてカスタム要素コールバックリアクションをキューに追加します。
elementが接続済みである場合、element、コールバック名「connectedCallback」および空の引数リストを用いてカスタム要素コールバックリアクションをキューに追加します。
definitionの構築スタックの末尾にelementを追加します。
Cをdefinitionのコンストラクタに設定します。
以下のサブステップを例外をキャッチしながら実行します:
definitionのシャドウを無効にするがtrueであり、elementのシャドウルートがnullでない場合、"NotSupportedError"のDOMExceptionを投げます。
これは、attachShadow()がカスタム要素定義の検索を使用しないために必要です。一方、attachInternals()は使用します。
elementのカスタム要素状態を「precustomized」に設定します。
Cを引数なしで構築した結果をconstructResultに設定します。
もしCが[CEReactions]拡張属性で装飾されたAPIを不適合に使用している場合、このアルゴリズムの開始時にキューに追加されたリアクションは、このステップ中にCが終了し、制御がこのアルゴリズムに戻る前に実行されます。そうでない場合、Cとアップグレードプロセスの残りが終了した後に実行されます。
もしSameValue(constructResult,
element)がfalseの場合、TypeErrorを投げます。
これは、Cがsuper()を呼び出す前に同じカスタム要素の別のインスタンスを構築するか、CがJavaScriptのreturn-override機能を使用してコンストラクタから任意のHTMLElementオブジェクトを返す場合に発生します。
次に、上記のステップが例外を投げたかどうかに関わらず、次のサブステップを実行します:
definitionの構築スタックの末尾から最後のエントリを削除します。
もしCがsuper()を呼び出すと(適合している場合はそうします)、このステップが成功すると、これはアルゴリズムの冒頭で押されたelementを置き換えたすでに構築されたマーカーになります。(HTML要素コンストラクタがこの置き換えを行います。)
もしCがsuper()を呼び出さない場合(つまり、適合していない)、またはHTML要素コンストラクタのいずれかのステップが例外を投げる場合、このエントリは依然としてelementであるでしょう。
最後に、上記のステップが例外を投げた場合、次のサブステップを実行します:
elementのカスタム要素定義をnullに設定します。
elementのカスタム要素リアクションキューを空にします。
例外を再スローします(このアルゴリズムを終了します)。
上記のステップが例外を投げた場合、elementのカスタム要素状態は「failed」または「precustomized」のままになります。
elementがフォーム関連カスタム要素である場合、次のサブステップを実行します:
elementのフォームオーナーをリセットします。elementがフォーム要素に関連付けられている場合、element、コールバック名「formAssociatedCallback」および「関連するフォーム」を含む引数リストを用いてカスタム要素コールバックリアクションをキューに追加します。
elementが無効化されている場合、element、コールバック名「formDisabledCallback」および「true」を含む引数リストを用いてカスタム要素コールバックリアクションをキューに追加します。
elementのカスタム要素状態を「custom」に設定します。
elementを入力として与えられた場合、要素をアップグレードを試みるために、次の手順を実行します:
definitionを、elementのノードドキュメント、elementの名前空間、elementのローカル名、およびelementのis値を与えてカスタム要素定義を検索した結果に設定します。
もしdefinitionがnullでない場合、elementとdefinitionを与えてカスタム要素アップグレードリアクションをキューに追加します。
カスタム要素は、特定の出来事に反応して 作者のコードを実行する能力を持っています:
接続されたとき、その
connectedCallbackが引数なしで呼び出されます。
切断されたとき、その
disconnectedCallbackが引数なしで呼び出されます。
別のドキュメントに採用された
とき、そのadoptedCallbackが呼び出され、古いドキュメントと新しいドキュメントが引数として渡されます。
任意の属性が変更されたり、追加されたり、削除されたり、置換されたりすると、その
attributeChangedCallbackが呼び出され、属性のローカル名、古い値、新しい値、名前空間が引数として渡されます。(属性の古い値または新しい値は、それぞれ追加または削除されたときにnullと見なされます。)
ユーザーエージェントがフォーム所有者をリセット
し、それによってフォーム所有者が変更されたとき、そのformAssociatedCallbackが呼び出され、新しいフォーム所有者(または所有者がいない場合はnull)が引数として渡されます。
フォームがリセットされたとき、その
formResetCallbackが呼び出されます。
無効
の状態が変わったとき、そのformDisabledCallbackが呼び出され、新しい状態が引数として渡されます。
ユーザーエージェントが、ユーザーの代理で、またはナビゲーションの一部として
フォーム関連カスタム要素の
値を更新すると、そのformStateRestoreCallbackが呼び出され、新しい状態と「autocomplete」または「restore」という理由を示す文字列が引数として渡されます。
これらの反応をまとめて、カスタム要素のリアクションと呼びます。
カスタム要素のリアクション が呼び出される方法は、繊細な操作の最中に作成者のコードを実行しないよう特別に配慮されています。実際には、「ユーザースクリプトに戻る直前まで」遅延されます。これにより、ほとんどの場合、同期的に実行されるように見えますが、複雑な複合操作(例:クローンや範囲操作など)の場合、すべての関連するユーザーエージェント処理ステップが完了した後に遅延され、バッチとして一緒に実行されます。
さらに、これらの反応の正確な順序は、以下に説明するやや複雑なキューのスタックシステムを介して管理されます。このシステムの意図は、カスタム要素のリアクションが常に それらのトリガーとなるアクションと同じ順序で呼び出されることを保証することです。少なくとも、単一のカスタム要素のローカルコンテキスト内ではそうなります。(ただし、カスタム要素のリアクションコードが独自の変異を行う可能性があるため、複数の要素間でのグローバルな順序保証を提供することはできません。)
各同一オリジンのウィンドウエージェントは、カスタム要素リアクションスタックを持ち、初期状態では空です。同一オリジンのウィンドウエージェントの現在の要素キューは、その要素キューがカスタム要素リアクションスタックの一番上にあるものです。スタックの各項目は、要素キューであり、これも初期状態では空です。要素キューの各項目は要素です。(これらの要素は、必ずしもカスタム要素であるとは限りません。このキューはアップグレードにも使用されるためです。)
すべてのカスタム要素のリアクションスタックには、関連付けられたバックアップ要素キューがあり、最初は空の要素キューです。要素は、バックアップ要素キューに対して、 DOMに影響を与える操作の際に[CEReactions]で装飾されたAPIや、パーサーの トークン用の要素を作成するアルゴリズムを経由せずに、プッシュされます。これの例は、ユーザーが開始した編集操作で、編集可能な要素の子孫や属性を変更する場合です。バックアップ要素キューを処理する際の再入を防ぐために、すべてのカスタム要素のリアクションスタックにはバックアップ要素キューを処理する フラグがあり、初期状態では設定されていません。
すべての要素には、カスタム要素のリアクションキューが関連付けられており、最初は空です。カスタム要素のリアクションキュー内の各項目は、次の2つのタイプのいずれかです:
アップグレードリアクションは、カスタム要素をアップグレードし、カスタム要素の定義を含みます。
コールバックリアクションは、ライフサイクルコールバックを呼び出し、コールバック関数と引数のリストを含みます。
これらは次の模式図でまとめられています:
適切な要素キューに要素をエンキューするには、要素 elementを指定して、次の手順を実行します:
reactionsStackをelementの関連エージェントの カスタム要素のリアクションスタックに設定します。
reactionsStackが空の場合、次を実行します:
elementをreactionsStackのバックアップ要素キューに追加します。
reactionsStackのバックアップ要素キューを処理するフラグが設定されている場合は、戻ります。
reactionsStackのバックアップ要素キューを処理する フラグを設定します。
マイクロタスクをキューに入れ、次の手順を実行します:
カスタム要素のリアクションを呼び出します、reactionsStackの バックアップ要素キュー内で。
reactionsStackのバックアップ要素キューを処理する フラグを解除します。
カスタム要素のコールバックリアクションをエンキューするには、カスタム要素であるelement、コールバック名callbackName、および引数のリストargsを指定して、次の手順を実行します:
definitionをelementのカスタム要素の定義に設定します。
callbackをdefinitionのライフサイクルコールバックの callbackNameキーに対応する値に設定します。
callbackがnullの場合、戻ります。
callbackNameが「attributeChangedCallback」の場合、次を実行します:
attributeNameをargsの最初の要素に設定します。
definitionの監視される属性に attributeNameが含まれていない場合、戻ります。
elementのカスタム要素のリアクションキューに新しいコールバックリアクションを追加します。コールバック関数はcallback、引数はargsです。
適切な要素キューに要素をエンキューするを、elementを指定して実行します。
カスタム要素のアップグレードリアクションをエンキューするには、要素 elementとカスタム要素の定義 definitionを指定して、次の手順を実行します:
elementのカスタム要素のリアクションキューに新しいアップグレードリアクションを追加し、カスタム要素の定義をdefinitionに設定します。
適切な要素キューに要素をエンキューするを、elementを指定して実行します。
カスタム要素のリアクションを呼び出すには、要素キュー queue内で次の手順を実行します:
queueが空ではない間、次を実行します:
elementをqueueからデキューした結果に設定します。
reactionsをelementのカスタム要素のリアクションキューに設定します。
reactionsが空でない限り、次を繰り返します:
reactionsの最初の要素を削除し、その要素をreactionに設定します。reactionのタイプに応じて次を実行します:
カスタム要素をアップグレードするを、 reactionのカスタム要素の定義を使用して実行します。
これにより例外がスローされた場合、その例外をキャッチし、例外を報告し、reactionのカスタム要素の定義に対応する JavaScriptオブジェクトの関連するレルムのグローバルオブジェクトに対して例外を報告します。
コールバック関数を引数とともに呼び出します、reactionの
"報告"とreactionの引数を指定し、thisをelementに設定して実行します。
カスタム要素のリアクションが適切にトリガーされることを保証するために、[CEReactions]というIDLの拡張属性を導入します。これにより、関連するアルゴリズムに追加のステップを補完して、カスタム要素のリアクションを適切に追跡し、呼び出すよう指示します。
[CEReactions]拡張属性は、引数を取らず、操作、属性、セッター、またはデリーター以外のものには現れてはなりません。また、読み取り専用属性には現れてはなりません。
[CEReactions]拡張属性で注釈された操作、属性、セッター、またはデリーターは、記述されたものに代わって次のステップを実行しなければなりません。
新しい要素キューを、このオブジェクトの関連エージェントのカスタム要素のリアクションスタックにプッシュします。
この構造のために元々指定されていたステップを実行し、例外が発生した場合はキャッチします。ステップが値を返す場合は、valueに返された値を設定します。例外をスローした場合は、exceptionにスローされた例外を設定します。
queueを、このオブジェクトの関連エージェントのカスタム要素のリアクションスタックからポップした結果に設定します。
queue内のカスタム要素のリアクションを呼び出します。
元のステップでexceptionがスローされた場合は、exceptionを再スローします。
元のステップでvalueが返された場合は、valueを返します。
この拡張属性の意図はやや微妙です。これを達成する一つの方法は、プラットフォーム上のすべての操作、属性、セッター、デリーターにこれらのステップを挿入し、必要のないケース(カスタム要素のリアクションが発生する可能性のあるDOMの変更がない場合)を最適化することを許可することです。
しかし、実際には、この不正確さがカスタム要素のリアクションの非互換実装につながる可能性があり、いくつかのケースでこれらのステップを呼び出すことを忘れる可能性があります。その代わりに、すべての関連するIDL構造を明示的に注釈するアプローチを選び、互換性のある動作を保証し、実装がこれらのステップが必要なすべてのケースを容易に特定できるようにしました。
ユーザーエージェントによって導入された非標準のAPIで、たとえば属性や子要素を変更することで、カスタム要素のコールバックリアクションをエンキューしたり、カスタム要素のアップグレードリアクションをエンキューするようなDOMの変更を引き起こす可能性がある場合、そのAPIも[CEReactions]属性で装飾する必要があります。
この執筆時点では、次の非標準またはまだ標準化されていないAPIがこのカテゴリに該当することが知られています:
HTMLInputElementのwebkitdirectoryおよびincrementalIDL属性
HTMLLinkElementのscopeIDL属性
特定の機能はカスタム要素の作成者にのみ提供され、カスタム要素の利用者には提供されません。これらの機能は、element.attachInternals()メソッドによって提供され、ElementInternalsのインスタンスを返します。ElementInternalsのプロパティおよびメソッドにより、ユーザーエージェントがすべての要素に提供する内部機能を制御できます。
element.attachInternals()
カスタム要素elementを対象としたElementInternalsオブジェクトを返します。elementがカスタム要素でない場合、"internals"機能が要素定義の一部として無効化されている場合、または同じ要素に対して2回呼び出された場合は、例外がスローされます。
各HTMLElementには付属内部機能(nullまたはElementInternalsオブジェクト)があり、初期値はnullです。
すべての現在のエンジンでサポートされています。
attachInternals()メソッドの手順は次の通りです。
thisのis値がnullでない場合、"NotSupportedError" DOMExceptionをスローします。
thisのノードドキュメント、その名前空間、ローカル名、そしてis値にnullを指定して、カスタム要素の定義を検索した結果をdefinitionとします。
definitionがnullである場合、"NotSupportedError" DOMExceptionをスローします。
definitionの内部機能の無効化がtrueである場合、"NotSupportedError" DOMExceptionをスローします。
thisの付属内部機能がnullでない場合、"NotSupportedError" DOMExceptionをスローします。
thisのカスタム要素の状態が"precustomized"または"custom"でない場合、"NotSupportedError" DOMExceptionをスローします。
thisの付属内部機能を、新しいElementInternalsインスタンス(そのターゲット要素がthisであるもの)に設定します。
ElementInternals
インターフェースすべての現在のエンジンでサポートされています。
ElementInternals
インターフェースの IDL は以下の通りで、各操作や属性は次のセクションで定義されています。
[Exposed =Window ]
interface ElementInternals {
// シャドウルートのアクセス
readonly attribute ShadowRoot ? shadowRoot ;
// フォーム関連カスタム要素
undefined setFormValue ((File or USVString or FormData )? value ,
optional (File or USVString or FormData )? state );
readonly attribute HTMLFormElement ? form ;
undefined setValidity (optional ValidityStateFlags flags = {},
optional DOMString message ,
optional HTMLElement anchor );
readonly attribute boolean willValidate ;
readonly attribute ValidityState validity ;
readonly attribute DOMString validationMessage ;
boolean checkValidity ();
boolean reportValidity ();
readonly attribute NodeList labels ;
// カスタム状態疑似クラス
[SameObject ] readonly attribute CustomStateSet states ;
};
// アクセシビリティセマンティクス
ElementInternals includes ARIAMixin ;
dictionary ValidityStateFlags {
boolean valueMissing = false ;
boolean typeMismatch = false ;
boolean patternMismatch = false ;
boolean tooLong = false ;
boolean tooShort = false ;
boolean rangeUnderflow = false ;
boolean rangeOverflow = false ;
boolean stepMismatch = false ;
boolean badInput = false ;
boolean customError = false ;
};
各 ElementInternals
には ターゲット要素 があり、それは カスタム要素 です。
internals.shadowRoot
internals の ターゲット要素 が シャドウホスト である場合、その ShadowRoot
を返します。それ以外の場合は null を返します。
すべての現在のエンジンでサポートされています。
shadowRoot ゲッターステップは以下の通りです:
もし target が シャドウホスト でない場合、null を返します。
shadow を target の シャドウルート とします。
もし shadow の 要素内部に利用可能 が false である場合、null を返します。
shadow を返します。
internals.setFormValue(value)
internals の ターゲット要素 の 状態 と 送信値 の両方を value に設定します。
value が null の場合、その要素はフォーム送信に参加しません。
internals.setFormValue(value, state)
internals の ターゲット要素 の 送信値 を value に設定し、その 状態 を state に設定します。
value が null の場合、その要素はフォーム送信に参加しません。
internals.form
internals.setValidity(flags, message [, anchor ])
internals の ターゲット要素 が flags
引数で示された制約に違反しているとマークし、要素の検証メッセージを message に設定します。anchor
が指定されている場合、ユーザーエージェントは、インタラクティブにフォームオーナーの検証が行われた際や reportValidity()
が呼び出された際に、internals の ターゲット要素 の制約の問題を示すためにそれを使用するかもしれません。
internals.setValidity({})
internals の ターゲット要素 が その制約を満たしている とマークします。
internals.willValidate
フォームが送信されるときに internals の ターゲット要素 が検証される場合は true を、それ以外の場合は false を返します。
internals.validity
internals の ターゲット要素 の ValidityState
オブジェクトを返します。
internals.validationMessage
もし internals の ターゲット要素 が検証された場合にユーザーに表示されるエラーメッセージを返します。
valid = internals.checkValidity()
internals の ターゲット要素 が有効性の問題を持たない場合は true を、そうでない場合は
false を返します。その後者の場合、invalid
イベントがその要素に発生します。
valid = internals.reportValidity()
internals の ターゲット要素 が有効性の問題を持たない場合は true を、それ以外の場合は
false を返し、invalid
イベントがその要素に発生し、(イベントがキャンセルされない限り)問題がユーザーに報告されます。
internals.labels
internals の ターゲット要素 が関連付けられているすべての NodeList
の label
要素を返します。
各 フォーム関連カスタム要素 は 送信値 を持っています。これは、フォーム送信時に一つ以上の エントリ を提供するために使用されます。送信値 の初期値は null であり、送信値 は
null、文字列、File、または
リスト
のいずれかであることができます。
各 フォーム関連カスタム要素 は 状態 を持っています。これは、ユーザーエージェントが要素のユーザー入力を復元するための情報です。状態 の初期値は null であり、状態 は null、文字列、File、または
リスト のいずれかであることができます。
setFormValue()
メソッドは、カスタム要素の作成者が要素の 送信値 と 状態 を設定し、それらをユーザーエージェントに伝えるために使用します。
ユーザーエージェントが フォーム関連カスタム要素 の 状態 を復元するのが良いと判断した場合、例えば ナビゲーション後 やユーザーエージェントの再起動後に、ユーザーエージェントはその要素に対して カスタム要素コールバック反応をエンキュー し、その要素に "formStateRestoreCallback" というコールバック名を付けて、復元されるべき状態を引数リストに含めて、"restore" を実行します。
ユーザーエージェントにフォーム入力補助機能がある場合、その機能が起動されたときには、カスタム要素コールバック反応をエンキュー し、フォーム関連カスタム要素 に対して "formStateRestoreCallback" というコールバック名を付けて、状態値履歴といくつかのヒューリスティックに基づいて決定された状態値を引数リストに含めて、"autocomplete" を実行するかもしれません。
一般的に、状態 はユーザーによって指定された情報であり、送信値 は正規化やサニタイズの後にサーバーに送信するのに適した値です。以下の例でこれを具体化します:
たとえば、日付を指定するためにユーザーに尋ねる フォーム関連カスタム要素 があるとします。ユーザーが "3/15/2019" と指定したが、コントロールは "2019-03-15" をサーバーに送信したいとします。"3/15/2019" は要素の 状態 であり、"2019-03-15" は 送信値 となります。
たとえば、既存の チェックボックス input
タイプの動作をエミュレートするカスタム要素を開発する場合、その 送信値 はその value コンテンツ属性の値、または文字列
"on" となります。その 状態 は
"checked"、"unchecked"、"checked/indeterminate"、または "unchecked/indeterminate" のいずれかになります。
すべての現在のエンジンでサポートされています。
setFormValue(value, state) メソッドのステップは次のとおりです:
もし element が フォーム関連カスタム要素 でない場合、"NotSupportedError" DOMException
をスローします。
もし value が FormData
オブジェクトでない場合、ターゲット要素
の 送信値 を
value に設定し、それ以外の場合は value の エントリリスト の クローン に設定します。
それ以外の場合、もし state が FormData
オブジェクトである場合、element の 状態 を state の エントリリスト の クローン に設定します。
それ以外の場合、element の 状態 を state に設定します。
各フォーム関連カスタム要素には、valueMissing、typeMismatch、patternMismatch、tooLong、tooShort、rangeUnderflow、rangeOverflow、stepMismatch、およびcustomErrorという有効性フラグがあります。これらは初期状態ではfalseです。
各フォーム関連カスタム要素には、検証メッセージ文字列があります。これの初期値は空の文字列です。
各フォーム関連カスタム要素には、検証アンカー要素があります。これの初期値はnullです。
すべての現在のエンジンでサポートされています。
setValidity(flags, message, anchor)メソッドの手順は次のとおりです:
もし element が フォーム関連カスタム要素 でない場合、"NotSupportedError" DOMException
をスローします。
もし flags が1つ以上のtrue値を含んでおり、message が指定されていないか空文字列である場合、TypeErrorをスローします。
各flag → valueのエントリに対して、element の同名の有効性フラグを value に設定します。
もし message が指定されていないか、すべてのelement の有効性フラグがfalseである場合、element の検証メッセージ を空文字列に設定し、そうでない場合は message に設定します。
もし element のcustomError有効性フラグがtrueである場合、element のカスタム有効性エラーメッセージ を
element の検証メッセージ
に設定します。そうでない場合、element のカスタム有効性エラーメッセージ を空文字列に設定します。
もし anchor が指定されていない場合、element の検証アンカー
をnullに設定します。それ以外の場合、もしanchorが element のシャドウを含む子孫 でない場合、"NotFoundError" DOMException
をスローします。それ以外の場合、element の検証アンカー を anchor に設定します。
ElementInternals/validationMessage
すべての現在のエンジンでサポートされています。
validationMessageのgetter手順は次のとおりです:
もし element がフォーム関連カスタム要素でない場合、"NotSupportedError" DOMException
をスローします。
elementの検証メッセージを返します。
エントリ構築アルゴリズムは、フォーム関連カスタム要素に対して、要素elementとエントリリストentry listが与えられた場合に、次の手順を実行します:
もしelementの送信値がエントリのリストである場合、elementの送信値の各項目をentry listに追加し、終了します。
この場合、ユーザーエージェントはnameコンテンツ属性の値を参照しません。フォーム関連カスタム要素の実装は、エントリの名前を決定する責任があります。これらの名前は、nameコンテンツ属性値に基づく文字列である場合や、nameコンテンツ属性に関連しない場合があります。
もし要素の送信値がnullでない場合、name属性の値と送信値を使用してエントリを作成し、それをentry listに追加します。
internals.role [ = value ]
internalsのターゲット要素に対して、デフォルトのARIAロールを設定または取得します。このロールは、ページ作者がrole属性を使用して上書きしない限り使用されます。
internals.aria* [ = value ]
internalsのターゲット要素に対して、デフォルトのARIA状態またはプロパティ値を設定または取得します。これらの値は、ページ作者がaria-*属性を使用して上書きしない限り使用されます。
各カスタム要素には、内部コンテンツ属性マップがあります。これはマップであり、初期状態では空です。これがプラットフォームのアクセシビリティAPIにどのように影響するかについては、ARIAおよびプラットフォームアクセシビリティAPIに関連する要件セクションを参照してください。
internals.states.add(value)
valueという文字列を要素の状態セットに追加して、擬似クラスとして公開します。
internals.states.has(value)
valueが要素の状態セットに含まれている場合はtrueを返し、そうでない場合はfalseを返します。
internals.states.delete(value)
要素の状態セットにvalueが存在する場合は、それを削除してtrueを返します。そうでない場合はfalseを返します。
internals.states.clear()
要素の状態セットからすべての値を削除します。
for (const stateName of internals.states)
for (const stateName of internals.states.entries())
for (const stateName of internals.states.keys())
for (const stateName of internals.states.values())
要素の状態セット内のすべての値を反復処理します。
internals.states.forEach(callback)
callbackを使用して、要素の状態セット内のすべての値を反復処理します。
internals.states.size
要素の状態セット内の値の数を返します。
各カスタム要素には、状態セットがあり、それは最初は空のCustomStateSetです。
[Exposed =Window ]
interface CustomStateSet {
setlike <DOMString >;
};
statesゲッターステップは、thisのターゲット要素の状態セットを返すことです。
状態セットは、文字列の存在/非存在によって表されるブール値の状態を公開できます。作成者が3つの値を持つ状態を公開したい場合、それは3つの排他的なブール状態に変換できます。例えば、readyStateという状態が"loading"、"interactive"、および"complete"の値を持つ場合、それを3つの排他的なブール状態"loading"、"interactive"、および"complete"にマッピングできます:
// readyState を他の値から "complete" に変更する。
this . _readyState = "complete" ;
this . _internals. states. delete ( "loading" );
this . _internals. states. delete ( "interactive" );
this . _internals. states. add ( "complete" );
この仕様では、パンくずリストナビゲーションメニューを機械で読み取れる形で記述する方法を提供していません。著者は、段落内にリンクを並べるだけで良いとされています。nav要素を使用して、これらの段落を含むセクションをナビゲーションブロックとしてマークすることができます。
次の例では、現在のページに2つのパスからアクセスできます。
< nav >
< p >
< a href = "/" > メイン</ a > ▸
< a href = "/products/" > 製品</ a > ▸
< a href = "/products/dishwashers/" > 食器洗い機</ a > ▸
< a > 中古</ a >
</ p >
< p >
< a href = "/" > メイン</ a > ▸
< a href = "/second-hand/" > 中古</ a > ▸
< a > 食器洗い機</ a >
</ p >
</ nav >
この仕様では、ページグループに適用されるキーワードのリスト(タグクラウドとしても知られています)をマークアップするための専用のマークアップは定義されていません。一般的に、著者はul要素を使用して、このようなリストを明示的なインラインカウントでマークアップし、その後それを非表示にしてスタイルシートを使用して表示効果に変換するか、SVGを使用することが推奨されます。
ここでは、3つのタグが短いタグクラウドに含まれています。
< style >
. tag-cloud > li > span { display : none ; }
. tag-cloud > li { display : inline ; }
. tag-cloud-1 { font-size : 0.7 em ; }
. tag-cloud-2 { font-size : 0.9 em ; }
. tag-cloud-3 { font-size : 1.1 em ; }
. tag-cloud-4 { font-size : 1.3 em ; }
. tag-cloud-5 { font-size : 1.5 em ; }
@ media speech {
. tag-cloud > li > span { display : inline }
}
</ style >
...
< ul class = "tag-cloud" >
< li class = "tag-cloud-4" >< a title = "28 instances" href = "/t/apple" > apple</ a > < span > (popular)</ span >
< li class = "tag-cloud-2" >< a title = "6 instances" href = "/t/kiwi" > kiwi</ a > < span > (rare)</ span >
< li class = "tag-cloud-5" >< a title = "41 instances" href = "/t/pear" > pear</ a > < span > (very popular)</ span >
</ ul >
各タグの実際の頻度は、title属性を使用して示されます。CSSスタイルシートが提供されており、このマークアップを異なるサイズの単語で構成されたクラウドに変換しますが、CSSをサポートしていない、または視覚的でないユーザーエージェントの場合、マークアップには
"(popular)" や "(rare)" などの注釈が含まれており、タグの頻度によってさまざまなタグを分類します。これにより、すべてのユーザーがこの情報を利用できるようになります。
ul要素が使用されるのは、順序が特に重要ではないためです。実際にはリストがアルファベット順に並んでいますが、タグの長さなどで順序が変更されても同じ情報を伝えることができます。
これらのa要素には、ページ自体に適用されるタグを表しているわけではないため、tag relキーワードは使用されません。これらはタグ自体を一覧表示するインデックスの一部に過ぎません。
この仕様では、会話、会議の議事録、チャットの記録、脚本の対話、インスタントメッセージのログ、その他の異なるプレイヤーが順番に発言する場面をマークアップするための特定の要素を定義していません。
代わりに、著者にはp要素と句読点を使用して会話をマークアップすることが推奨されます。スタイル設定のために話者をマークする必要がある場合は、spanまたはbを使用することが推奨されます。i要素でテキストを囲んだ段落は、舞台指示をマークアップするために使用できます。
この例では、アボットとコステロの有名なスケッチ「誰が一塁か」の抜粋を使用してこれを示しています。
< p > Costello: Look, you gotta first baseman?
< p > Abbott: Certainly.
< p > Costello: Who's playing first?
< p > Abbott: That's right.
< p > Costello becomes exasperated.
< p > Costello: When you pay off the first baseman every month, who gets the money?
< p > Abbott: Every dollar of it.
以下の抜粋は、IM(インスタントメッセージ)会話ログがどのようにマークアップされるかを示しており、各行にUnixタイムスタンプを提供するためにdata要素を使用しています。タイムスタンプがtime要素がサポートしていない形式で提供されていることに注意してください。そのため、Unix
time_tタイムスタンプとしてdata要素が使用されています。もし著者がtime要素でサポートされている日時形式のいずれかを使用してデータをマークアップしたいと考えた場合、その要素をdataの代わりに使用することができました。これは、ページ著者との調整なしにデータ解析ツールがタイムスタンプを明確に検出できるという利点をもたらす可能性があります。
< p > < data value = "1319898155" > 14:22</ data > < b > egof</ b > I'm not that nerdy, I've only seen 30% of the star trek episodes
< p > < data value = "1319898192" > 14:23</ data > < b > kaj</ b > if you know what percentage of the star trek episodes you have seen, you are inarguably nerdy
< p > < data value = "1319898200" > 14:23</ data > < b > egof</ b > it's unarguably
< p > < data value = "1319898228" > 14:23</ data > < i > * kaj blinks</ i >
< p > < data value = "1319898260" > 14:24</ data > < b > kaj</ b > you are not helping your case
HTMLにはグラフをマークアップするための適切な方法がないため、ゲームのインタラクティブな会話の説明をマークアップするのが難しくなっています。この例は、会話の各ポイントで可能な応答をリストするためにdl要素を使用する一つの可能な慣習を示しています。また、会話をDOTファイルの形式で記述し、その結果をSVG画像として出力し、ドキュメント内に配置するというオプションも考慮する価値があります。[DOT]
< p > Next, you meet a fisher. You can say one of several greetings:
< dl >
< dt > "Hello there!"
< dd >
< p > She responds with "Hello, how may I help you?"; you can respond with:
< dl >
< dt > "I would like to buy a fish."
< dd > < p > She sells you a fish and the conversation finishes.
< dt > "Can I borrow your boat?"
< dd >
< p > She is surprised and asks "What are you offering in return?".
< dl >
< dt > "Five gold." (if you have enough)
< dt > "Ten gold." (if you have enough)
< dt > "Fifteen gold." (if you have enough)
< dd > < p > She lends you her boat. The conversation ends.
< dt > "A fish." (if you have one)
< dt > "A newspaper." (if you have one)
< dt > "A pebble." (if you have one)
< dd > < p > "No thanks", she replies. Your conversation options
at this point are the same as they were after asking to borrow
her boat, minus any options you've suggested before.
</ dl >
</ dd >
</ dl >
</ dd >
< dt > "Vote for me in the next election!"
< dd > < p > She turns away. The conversation finishes.
< dt > "Madam, are you aware that your fish are running away?"
< dd >
< p > She looks at you skeptically and says "Fish cannot run, miss".
< dl >
< dt > "You got me!"
< dd > < p > The fisher sighs and the conversation ends.
< dt > "Only kidding."
< dd > < p > "Good one!" she retorts. Your conversation options at this
point are the same as those following "Hello there!" above.
< dt > "Oh, then what are they doing?"
< dd > < p > She looks at her fish, giving you an opportunity to steal
her boat, which you do. The conversation ends.
</ dl >
</ dd >
</ dl >
一部のゲームでは、会話がより簡単で、各キャラクターが言う固定されたセリフのセットを持つだけです。この例では、ゲームのFAQ/ウォークスルーが各キャラクターの既知の可能な応答のいくつかをリストしています:
< section >
< h1 > Dialogue</ h1 >
< p >< small > Some characters repeat their lines in order each time you interact
with them, others randomly pick from amongst their lines. Those who respond in
order have numbered entries in the lists below.</ small >
< h2 > The Shopkeeper</ h2 >
< ul >
< li > How may I help you?
< li > Fresh apples!
< li > A loaf of bread for madam?
</ ul >
< h2 > The pilot</ h2 >
< p > Before the accident:
< ul >
< li > I'm about to fly out, sorry!
< li > Sorry, I'm just waiting for flight clearance and then I'll be off!
</ ul >
< p > After the accident:
< ol >
< li > I'm about to fly out, sorry!
< li > Ok, I'm not leaving right now, my plane is being cleaned.
< li > Ok, it's not being cleaned, it needs a minor repair first.
< li > Ok, ok, stop bothering me! Truth is, I had a crash.
</ ol >
< h2 > Clan Leader</ h2 >
< p > During the first clan meeting:
< ul >
< li > Hey, have you seen my daughter? I bet she's up to something nefarious again...
< li > Nice weather we're having today, eh?
< li > The name is Bailey, Jeff Bailey. How can I help you today?
< li > A glass of water? Fresh from the well!
</ ul >
< p > After the earthquake:
< ol >
< li > Everyone is safe in the shelter, we just have to put out the fire!
< li > I'll go and tell the fire brigade, you keep hosing it down!
</ ol >
</ section >
HTMLには、脚注をマークアップするための専用の仕組みがありません。ここでは、推奨される代替手段を紹介します。
短いインライン注釈には、title属性を使用することができます。
この例では、対話の2つの部分に対して、title属性を使用して脚注のような内容が注釈されています。
< p > < b > 顧客</ b > : こんにちは!クレームを申し立てたいのですが。こんにちは。お嬢さん?
< p > < b > 店員</ b > : < span title = "What do you" の口語的発音
> 「Watcha」</ span > どうしましたか?
< p > < b > 顧客</ b > : ええと、すみません、風邪をひいているんです。クレームを申し立てたいのですが。
< p > < b > 店員</ b > : すみませんが、< span title = "これはもちろん嘘です。" > 昼食のために閉店します</ span > 。
残念ながら、title属性に頼ることは、現在では推奨されていません。多くのユーザーエージェントが、この仕様に必要とされるようにアクセシブルな方法で属性を表示していないからです(例えば、マウスなどのポインティングデバイスが必要で、ツールチップが表示される必要があり、キーボードのみのユーザーや現代の携帯電話やタブレットを持つタッチスクリーンユーザーを除外してしまいます)。
もしtitle属性が使用される場合は、CSSを使用して、その属性を持つ要素に読者の注意を引くことができます。
例えば、次のCSSは、title属性を持つ要素の下に破線を引きます。
[title] { border-bottom : thin dashed; }
長い注釈には、a要素を使用し、文書内の後の要素にリンクする必要があります。慣例として、リンクの内容は四角括弧内の数字とします。
この例では、対話の中で脚注がダイアログの下の段落にリンクしています。その段落は対話に戻るリンクを相互に含んでおり、ユーザーが脚注の場所に戻ることができるようにしています。
< p > アナウンサー: ナンバー16: < i > 手</ i > .
< p > インタビュアー: こんばんは。本日はスタジオに、ここ数年間、人々に反対意見を述べ続けているノーマン・セント・ジョン・ポールヴォールター氏をお迎えしています。ポールヴォールターさん、なぜ< em > そう</ em > しているのですか?
< p > ノーマン: していません。< sup >< a href = "#fn1" id = "r1" > [1]</ a ></ sup >
< p > インタビュアー: あなたは私にそう言いました!
...
< section >
< p id = "fn1" >< a href = "#r1" > [1]</ a > これは当然ながら嘘ですが、逆説的に言えば、もしそれが真実であれば、彼はインタビュアーに反論することなくそれを言うことはできず、それによってそれが偽であることを意味します。</ p >
</ section >
サイドノート、テキスト全体に適用される長い注釈には、aside要素を使用する必要があります。
この例では、対話の後にサイドバーが表示され、そのコンテキストが示されています。
< p > < span class = "speaker" > 顧客</ span > : このレコードは傷があるので買いません。
< p > < span class = "speaker" > 店員</ span > : すみません?
< p > < span class = "speaker" > 顧客</ span > : このレコードは傷があるので買いません。
< p > < span class = "speaker" > 店員</ span > : いやいや、これはタバコ屋です。
< aside >
< p > 1970年、イギリス帝国は滅び、その街には多くの外国人が歩いていました — その多くはハンガリー人です
(街ではなく — 外国人です)。残念ながら、アレクサンダー・ヤルトが無能なフレーズブックを出版していました。
</ aside >
図や表には、脚注を対応するfigcaptionやcaption要素、または周囲の文章に含めることができます。
この例では、表に脚注があり、それが文章で示されています。figure要素が使用され、表と脚注の組み合わせに単一の説明文を与えています。
< figure >
< figcaption > 表1. 騎士のための代替活動。</ figcaption >
< table >
< tr >
< th > 活動
< th > 場所
< th > 費用
</ tr >
< tr >
< td > ダンス
< td > 可能な限りどこでも
< td > £0< sup >< a href = "#fn1" > 1</ a ></ sup >
</ tr >
< tr >
< td > ルーチン、コーラスシーン</ sup >< a href = "#fn2" > 2</ a ></ sup >
< td > 公表されていない
< td > 公表されていない
</ tr >
< tr >
< td > 食事</ sup >< a href = "#fn3" > 3</ a ></ sup >
< td > キャメロット
< td > ハム、ジャム、スパムの費用</ sup >< a href = "#fn4" > 4</ a ></ sup >
</ tr >
</ table >
< p id = "fn1" > 1. 推定。</ p >
< p id = "fn2" > 2. 足技が見事。</ p >
< p id = "fn3" > 3. 品質は「良い」と評価されています。</ p >
< p id = "fn4" > 4. 非常に多い。</ p >
</ figure >
次のいずれかに該当する場合、要素は実際に無効化されたと見なされます。
button 要素が 無効化された 場合
input 要素が 無効化された 場合
select 要素が 無効化された 場合
textarea 要素が 無効化された 場合
optgroup 要素に disabled
属性がある場合
option 要素が 無効化された 場合
fieldset 要素が 無効化されたフィールドセット である場合
この定義は、どの要素がフォーカス可能であるか、またどの要素が :enabled や :disabled 疑似クラスに該当するかを判断するために使用されます。
CSS Values and Unitsは、`attr()`関数の属性名の大文字小文字の区別について、ホスト言語で定義することを残しています。[CSSVALUES]
CSSの`attr()`関数の属性名部分をHTML文書内のHTML要素の名前空間のない属性名と比較する場合、CSS `attr()` 関数の名前部分は、まずASCII小文字に変換する必要があります。他の属性と比較する場合、元の大文字小文字を維持して比較します。いずれの場合も、マッチするためには値が互いに同一である必要があり(したがって、比較は大文字小文字を区別します)。
これは、次のセクションで指定されたCSSの属性セレクターの名前部分と比較するのと同じです。
Selectorsは、要素名、属性名、および属性値の大文字小文字の区別をホスト言語で定義することを残しています。[SELECTORS]
CSS要素型セレクターをHTML文書内のHTML要素名と比較する場合、まずそのCSS要素型セレクターをASCII小文字に変換する必要があります。同じセレクターを他の要素と比較する場合は、元の大文字小文字を維持して比較します。いずれの場合も、比較対象は大文字小文字を区別して一致させる必要があります。
CSS属性セレクターの名前部分をHTML文書内のHTML要素の属性名と比較する場合、まずそのCSS属性セレクターの名前部分をASCII小文字に変換する必要があります。同じセレクターを他の属性と比較する場合は、元の大文字小文字を維持して比較します。いずれの場合も、比較は大文字小文字を区別して行われます。
HTML文書内のHTML要素に対する属性セレクターは、以下の名前を持つ属性の値をASCII大文字小文字を区別しないものとして扱う必要があります:
accept
accept-charset
align
alink
axis
bgcolor
charset
checked
clear
codetype
color
compact
declare
defer
dir
direction
disabled
enctype
face
frame
hreflang
http-equiv
lang
language
link
media
method
multiple
nohref
noresize
noshade
nowrap
readonly
rel
rev
rules
scope
scrolling
selected
shape
target
text
type
valign
valuetype
vlink
例えば、セレクター [bgcolor="#ffffff"] は、bgcolor 属性が
#ffffff、#FFFFFF、#fffFFF
のいずれかの値を持つHTML要素と一致します。これには、bgcolor が特定の要素(例:div)に効果がない場合も含まれます。
セレクター [type=a s] は、type 属性の値が a のHTML要素と一致しますが、A
の場合は一致しません。これは、s フラグによるものです。
他のすべての属性値および他のすべてのものは、セレクターのマッチングの目的では完全に同一であると扱う必要があります。これには以下が含まれます:
Selectorsは、IDおよびクラスセレクター(例:#foo および .bar)が クイークモードの文書の要素に対して一致する場合、大文字小文字を区別しないASCIIで一致させることを定義しています。ただし、id
や class を名前部分とする属性セレクターには、これが適用されません。セレクター [class="foobar"]
は、その値をクイークモードであっても大文字小文字を区別して扱います。
HTMLで使用できる動的なセレクターがいくつかあります。このセクションでは、これらのセレクターがHTML要素に一致する条件を定義します。[SELECTORS] [CSSUI]
:defined
すべての現在のエンジンでサポートされています。
:link
すべての現在のエンジンでサポートされています。
:visited
すべての現在のエンジンでサポートされています。
すべての a 要素が href
属性を持ち、すべての area 要素が href
属性を持つ場合、それらは :link および
:visited
のいずれかに一致しなければなりません。
その他の仕様は、この要素がこれらの 擬似クラスにどのようにマッチするかに関する、より具体的なルールを適用する可能性があります。この要件の直接的な実装に伴ういくつかのプライバシー問題を軽減するためです。
:active
すべての現在のエンジンでサポートされています。
:active 擬似クラスは、ユーザーが
アクティブ化している間
の要素に
マッチするように定義されています。
特定の要素が アクティブ化されているかどうかを判断するために、
:active 擬似クラス
を定義するためだけに、HTMLユーザーエージェントは次のリストの最初の関連エントリを使用する必要があります。
ボタン 要素である場合
input 要素であり、その
type 属性が Submit
Button, Image Button, Reset
Button, または Button 状態のいずれかにある場合
a 要素であり、
href
属性を持っている場合
area 要素であり、
href
属性を持っている場合
その要素は、正式なアクティベーション状態にある場合、アクティブ化されていると見なされます。
たとえば、ユーザーがキーボードを使用してスペースバーを押すことで ボタン
要素を押している場合、その要素は 擬似クラス
に一致します。このイベントは、要素が keydown
イベントを受信した時点から、keyup
イベントを受信した時点までの間に発生します。
その要素は、アクティブ化されていると見なされます。
要素は、ユーザーがその要素の アクティベーション動作 をトリガーする意図を示し始めた時点から、ユーザーがその要素の アクティベーション動作 をトリガーする意図を示すのを停止した時点、またはその要素の アクティベーション動作 が終了した時点のいずれか早い時点までの間、「正式なアクティベーション状態」にあると見なされます。
要素は、ユーザーがポインティングデバイスを使用して要素を指し示している間、そのポインティングデバイスが「ダウン」状態にある間(例:マウスの場合、マウスボタンが押されている時点からそれが離される時点まで。マルチタッチ環境での指の場合、指がディスプレイ面に触れている間)、「アクティブに指されている」と見なされます。
セレクタで定義されているように、:active は、アクティブ化されている要素のフラットツリーの先祖要素にも一致します。[SELECTORS]
さらに、ラベル付けされたコントロール要素であり、現在 :active に一致している要素の label 要素も、:active に一致します。ただし、それは アクティブ化されているとは見なされません。
:hover
すべての現在のエンジンでサポートされています。
:hover 疑似クラスは、ユーザーがポインティングデバイスで要素を指定する間に、その要素に一致するように定義されています。
Selectors の定義によると、:hover は、フラットツリー内の先祖要素にも一致します。
さらに、現在 :hover に一致している label 要素の ラベル付きコントロール である任意の要素も、:hover に一致します。しかし、それは指定されたとは見なされません。
特に次のようなフラグメントを考えてみましょう。
< p > < label for = c > < input id = a > </ label > < span id = b > < input id = c > </ span > </ p >
ユーザーがポインティングデバイスで ID "a" の要素を指定すると、p
要素(上記のスニペットには表示されていないすべての先祖要素)、label 要素、ID
"a" の要素、および ID "c" の要素が :hover 疑似クラスに一致します。ID
"a" の要素は指定されたことで一致し、label および p
要素はフラットツリーの先祖要素に関する条件によって一致し、ID "c" の要素はラベル付きコントロールに関する上記の追加条件を通じて一致します(つまり、その label 要素が :hover に一致しているため)。しかし、ID
"b" の要素は :hover
には一致しません。そのフラットツリーの子孫が指定されていないためです。
:focus
すべての現行エンジンでサポートされています。
CSS の :focus
疑似クラスに関して、要素がフォーカスを受けている
状態は次の場合です:
それ自体がナビゲート可能なコンテナではない場合; および
次のいずれかが真である場合:
それがトップレベルのトラバーサブルの現在のフォーカスチェーンに リストされている要素の一つである; または
そのシャドウルート shadowRoot が null でなく、かつその shadowRoot が少なくとも一つの フォーカスを受けている要素の ルートである。
:target
すべての現行エンジンでサポートされています。
CSS の :target
疑似クラスに関して、ドキュメントのターゲット要素は、
ドキュメントの
ターゲット要素が null でない場合はその要素のリストであり、
それが null の場合は要素を含まないリストです。[SELECTORS]
:popover-open
すべての現行エンジンでサポートされています。
:popover-open
疑似クラスは、HTML
要素の
popover属性が
ポップオーバーなしの状態でなく、
ポップオーバー表示状態が
表示されているものに一致するように定義されています。
:enabled
すべての現行エンジンでサポートされています。
:enabled 疑似クラスは、ボタン、
入力、セレクト、テキストエリア、
optgroup、
オプション、fieldset要素、または
フォーム関連のカスタム要素で、
実際には無効化されていないものに一致しなければなりません。
:disabled
すべての現行エンジンでサポートされています。
:disabled 疑似クラスは、実際に無効化されているすべての要素に一致しなければなりません。
:checked
すべての現行エンジンでサポートされています。
:indeterminate
すべての現行エンジンでサポートされています。
:indeterminate
疑似クラス
は、次のいずれかのカテゴリに該当する要素に一致しなければなりません:
:default
すべての現行エンジンでサポートされています。
:placeholder-shown
:placeholder-shown
疑似クラスは、次のいずれかのカテゴリに該当する要素に一致しなければなりません:
input要素で、
placeholder
属性を持っており、その値が現在ユーザーに表示されているもの。
textarea要素で、
placeholder
属性を持っており、その値が現在ユーザーに表示されているもの。
:valid
すべての現行エンジンでサポートされています。
:invalid
すべての現行エンジンでサポートされています。
:invalid 疑似クラスは、次のいずれかのカテゴリに該当する要素に一致しなければなりません:
form要素で、
その所有者が制約の検証候補であり、かつ制約を満たしていない要素を一つ以上持つもの。
fieldset
要素で、検証候補でありながら制約を満たしていない子孫要素を一つ以上持つもの。
:user-valid
:user-valid
疑似クラスは、次の要素に一致しなければなりません:
:user-invalid
:user-invalid
疑似クラスは、次の要素に一致しなければなりません:
:in-range
すべての現行エンジンでサポートされています。
:in-range 疑似クラスは、制約の検証候補であり、範囲制限を持つ要素で、かつ
アンダーフローまたは
オーバーフロー
のいずれでもないものに一致しなければなりません。
:out-of-range
すべての現行エンジンでサポートされています。
:out-of-range 疑似クラスは、制約の検証候補であり、範囲制限を持つ要素で、かつ
アンダーフローまたは
オーバーフロー
のいずれかであるものに一致しなければなりません。
:required
すべての現行エンジンでサポートされています。
:optional
すべての現行エンジンでサポートされています。
:autofill
:-webkit-autofill
:autofillおよび:-webkit-autofill
疑似クラスは、ユーザーエージェントによって自動入力されたinput要素に一致しなければなりません。
これらの疑似クラスは、ユーザーが自動入力されたフィールドを編集すると一致しなくなります。
このような自動入力が発生する一つの方法は、autocomplete
属性を使用することですが、ユーザーエージェントはその属性が関与していなくても自動入力を行うことがあります。
:read-only
すべての現行エンジンでサポートされています。
:read-write
すべての現行エンジンでサポートされています。
:read-write
疑似クラスは、セレクターの目的上、次のカテゴリのいずれかに該当するものとして
ユーザーが変更可能と見なされる要素に一致しなければなりません。 [SELECTORS]
input
要素で、readonly
属性が指定されておらず、変更可能であり(すなわち、readonly
属性が指定されておらず、かつ無効
でないもの)
textarea
要素で、readonly
属性が指定されておらず、無効でないもの
input
要素でもtextarea
要素でもないもの
:read-only
疑似クラスは、その他のすべてのHTML要素に一致しなければなりません。
:modal
:modal 疑似クラスは、次のいずれかのカテゴリに該当する要素に一致しなければなりません:
dialog
要素で、モーダルフラグがtrueであるもの
:dir(ltr)
:dir(rtl)
:state(identifier)
疑似クラスは、カスタム要素の状態セットのセットエントリにidentifierが含まれているすべての要素に一致しなければなりません。
:playing
:playing 疑似クラスは、メディア要素のpaused属性がfalseであるすべての要素に一致しなければなりません。
:paused
:seeking
:seeking 疑似クラスは、メディア要素のseeking属性がtrueであるすべての要素に一致しなければなりません。
:buffering
:buffering
疑似クラスは、メディア要素のpaused属性がfalseであり、
networkState属性がNETWORK_LOADINGであり、
レディ状態がHAVE_CURRENT_DATA以下であるすべての要素に一致しなければなりません。
:stalled
:stalled 疑似クラスは、:buffering
疑似クラスに一致し、現在停止しているがtrueであるすべての要素に一致しなければなりません。
:muted
:volume-locked
:volume-locked
疑似クラスは、ユーザーエージェントのボリュームロックがtrueであるときに、すべてのメディア要素に一致しなければなりません。
この仕様書では、:lang()動的疑似クラスが要素に一致するタイミングについて定義していません。これは言語に依存しない方法でSelectorsにおいて十分に詳細に定義されています。
[SELECTORS]
このセクションは規範的ではありません。
時々、特定の機械可読ラベルでコンテンツに注釈を付けることが望ましい場合があります。例えば、汎用スクリプトがページにカスタマイズされたサービスを提供できるようにしたり、複数の協力している著者からのコンテンツを一つのスクリプトで一貫した方法で処理できるようにしたりするためです。
この目的のために、著者はこのセクションで説明されているマイクロデータ機能を使用できます。マイクロデータを使用すると、既存のコンテンツと並行して、名前と値のペアのネストされたグループをドキュメントに追加できます。
このセクションは規範的ではありません。
高レベルでは、マイクロデータは名前と値のペアのグループで構成されています。これらのグループはアイテムと呼ばれ、それぞれの名前と値のペアはプロパティです。アイテムとプロパティは通常の要素で表されます。
アイテムを作成するには、itemscope属性を使用します。
アイテムにプロパティを追加するには、アイテムの子孫要素にitemprop属性を使用します。
ここには2つのアイテムがあり、それぞれが「name」というプロパティを持っています:
< div itemscope >
< p > 私の名前は < span itemprop = "name" > エリザベス</ span > .</ p >
</ div >
< div itemscope >
< p > 私の名前は < span itemprop = "name" > ダニエル</ span > .</ p >
</ div >
マイクロデータ関連の属性を持たないマークアップは、マイクロデータモデルに何の影響も与えません。
次の2つの例は、それぞれ前の2つの例とマイクロデータのレベルではまったく同等です:
< div itemscope >
< p > 私の < em > 名前</ em > は < span itemprop = "name" > エ< strong > リザベス</ strong > ベス</ span > .</ p >
</ div >
< section >
< div itemscope >
< aside >
< p > 私の名前は < span itemprop = "name" >< a href = "/?user=daniel" > ダニエル</ a ></ span > .</ p >
</ aside >
</ div >
</ section >
プロパティには、一般的に文字列の値が含まれます。
ここでは、アイテムには3つのプロパティがあります:
< div itemscope >
< p > 私の名前は < span itemprop = "name" > ニール</ span > .</ p >
< p > 私のバンドの名前は < span itemprop = "band" > Four Parts Water</ span > .</ p >
< p > 私は < span itemprop = "nationality" > 英国人</ span > .</ p >
</ div >
文字列の値がURLである場合、それはa要素とそのhref属性、img要素とそのsrc属性、または外部リソースへのリンクまたは埋め込みを行うその他の要素を使用して表現されます。
この例では、アイテムには「image」というプロパティが1つあり、その値はURLです:
< div itemscope >
< img itemprop = "image" src = "google-logo.png" alt = "Google" >
</ div >
文字列の値が人間にとって適していない機械可読形式である場合、それはvalue属性を持つdata要素を使用して表現され、その人間が読み取れるバージョンが要素の内容として提供されます。
ここでは、プロパティの値が製品IDであるアイテムがあります。IDは人間向けではないので、製品の名前が人間に見えるテキストとして使用されています:
< h1 itemscope >
< data itemprop = "product-id" value = "9678AOU879" > インスティゲーター 2000</ data >
</ h1 >
数値データの場合、meter要素とそのvalue属性を使用することができます。
ここでは、meter要素を使用して評価が行われています。
< div itemscope itemtype = "http://schema.org/Product" >
< span itemprop = "name" > パナソニック ホワイト 60L 冷蔵庫</ span >
< img src = "panasonic-fridge-60l-white.jpg" alt = "" >
< div itemprop = "aggregateRating" itemscope itemtype = "http://schema.org/AggregateRating" >
< meter itemprop = "ratingValue" min = 0 value = 3.5 max = 5 > 評価 3.5/5</ meter >
(基づく < span itemprop = "reviewCount" > 11</ span > 顧客レビュー)
</ div >
</ div >
同様に、日付や時間に関連するデータには、time要素とそのdatetime属性を使用することができます。
この例では、アイテムには「birthday」というプロパティが1つあり、その値は日付です:
< div itemscope >
私は < time itemprop = "birthday" datetime = "2009-05-10" > 2009年5月10日</ time > に生まれました。
</ div >
プロパティ自体が名前と値のペアのグループである場合、プロパティを宣言する要素にitemscope属性を付けることで実現できます。
他のアイテムの一部ではないアイテムはトップレベルのマイクロデータアイテムと呼ばれます。
この例では、外側のアイテムは人物を表し、内側のアイテムはバンドを表しています:
< div itemscope >
< p > 名前: < span itemprop = "name" > アマンダ</ span ></ p >
< p > バンド: < span itemprop = "band" itemscope > < span itemprop = "name" > ジャズバンド</ span > (< span itemprop = "size" > 12</ span > 人のプレイヤー)</ span ></ p >
</ div >
ここで、外側のアイテムには「name」と「band」の2つのプロパティがあります。「name」は「アマンダ」、そして「band」はそれ自体がアイテムで、「name」と「size」の2つのプロパティを持っています。バンドの「name」は「ジャズバンド」、そして「size」は「12」です。
この例の外側のアイテムは、トップレベルのマイクロデータアイテムです。
itemscope属性を持つ要素の子孫ではないプロパティは、itemref属性を使用してアイテムに関連付けることができます。この属性は、itemscope属性を持つ要素の子孫に加えて、クロールする要素のIDリストを指定します。
この例は前の例と同じですが、すべてのプロパティがアイテムから分離されています:
< div itemscope id = "amanda" itemref = "a b" ></ div >
< p id = "a" > 名前: < span itemprop = "name" > アマンダ</ span ></ p >
< div id = "b" itemprop = "band" itemscope itemref = "c" ></ div >
< div id = "c" >
< p > バンド: < span itemprop = "name" > ジャズバンド</ span ></ p >
< p > サイズ: < span itemprop = "size" > 12</ span > 人のプレイヤー</ p >
</ div >
これは前の例と同じ結果をもたらします。最初のアイテムには2つのプロパティ、「name」が「アマンダ」に設定され、「band」が別のアイテムに設定されています。2番目のアイテムにはさらに2つのプロパティ、「name」が「ジャズバンド」に、「size」が「12」に設定されています。
アイテムには、同じ名前で異なる値を持つ複数のプロパティを持たせることができます。
この例は、2つのフレーバーを持つアイスクリームを説明しています:
< div itemscope >
< p > 私のお気に入りのアイスクリームのフレーバー:</ p >
< ul >
< li itemprop = "flavor" > レモンシャーベット</ li >
< li itemprop = "flavor" > アプリコットシャーベット</ li >
</ ul >
</ div >
これにより、「flavor」という2つのプロパティを持ち、それぞれ「レモンシャーベット」と「アプリコットシャーベット」という値を持つアイテムが作成されます。
プロパティを導入する要素は、重複を避けるために、同じ値を持つプロパティがある場合、一度に複数のプロパティを導入することもできます。
ここでは、2つのプロパティ「favorite-color」と「favorite-fruit」を持つアイテムがあり、どちらも値は「オレンジ」に設定されています:
< div itemscope >
< span itemprop = "favorite-color favorite-fruit" > オレンジ</ span >
</ div >
マイクロデータと、それがマークアップされているドキュメントのコンテンツとの間には、関連性がないことに注意することが重要です。
例えば、次の2つの例には意味的な違いはありません:
< figure >
< img src = "castle.jpeg" >
< figcaption >< span itemscope >< span itemprop = "name" > ザ・キャッスル</ span ></ span > (1986)</ figcaption >
</ figure >
< span itemscope >< meta itemprop = "name" content = "ザ・キャッスル" ></ span >
< figure >
< img src = "castle.jpeg" >
< figcaption > ザ・キャッスル (1986)</ figcaption >
</ figure >
どちらもキャプション付きの図を持ち、どちらも図とは無関係に「name」という名前と「ザ・キャッスル」という値を持つアイテムを持っています。違いは、キャプションがドキュメントからドラッグアウトされた場合、前者の場合にはアイテムがドラッグ&ドロップデータに含まれることです。どちらの場合も、画像はアイテムと何の関連性もありません。
このセクションは規範的ではありません。
前のセクションの例では、マイクロデータが再利用されることを想定していないページにどのように情報をマークアップできるかを示しました。しかし、マイクロデータは、他の著者や読者が協力してマークアップの新しい使用方法を作成できるコンテキストで使用される場合に最も有用です。
この目的のために、各アイテムに「https://example.com/person」や「https://example.org/cat」、「https://band.example.net/」のようなタイプを指定する必要があります。タイプはURLとして識別されます。
アイテムのタイプは、itemtype属性の値として、itemscope属性と同じ要素に指定されます。
ここでは、アイテムのタイプが「https://example.org/animals#cat」となっています:
< section itemscope itemtype = "https://example.org/animals#cat" >
< h1 itemprop = "name" > Hedral</ h1 >
< p itemprop = "desc" > Hedral is a male american domestic
shorthair, with a fluffy black fur with white paws and belly.</ p >
< img itemprop = "img" src = "hedral.jpeg" alt = "" title = "Hedral, age 18 months" >
</ section >
この例では、「https://example.org/animals#cat」アイテムには、「name」(「Hedral」)、「desc」(「Hedral is...」)、「img」(「hedral.jpeg」)の3つのプロパティがあります。
タイプはプロパティにコンテキストを提供し、したがって語彙を選択します。「https://census.example/person」というタイプのアイテムに指定された「class」というプロパティは、個人の経済的階級を指すかもしれませんが、「https://example.com/school/teacher」というタイプのアイテムに指定された「class」というプロパティは、教師が割り当てられた教室を指すかもしれません。いくつかのタイプは語彙を共有することができます。たとえば、「https://example.org/people/teacher」と「https://example.org/people/engineer」のタイプは、同じ語彙を使用するように定義できます(ただし、いくつかのプロパティは両方のケースでは特に有用ではないかもしれません。たとえば、「https://example.org/people/engineer」タイプは通常、「classroom」プロパティと一緒に使用されないかもしれません)。同じ語彙を使用するように定義された複数のタイプは、属性の値にスペースで区切られたリストとしてURLを列挙することで、1つのアイテムに与えることができます。ただし、異なる語彙を使用しないタイプを1つのアイテムに与えることはできません。
このセクションは規範的ではありません。
時折、アイテムが、ISBN番号のようなグローバル識別子を持つトピックについての情報を提供することがあります。
itemtype属性によって識別される語彙は、itemid属性に指定されたURLとしてグローバル識別子を表現することで、アイテムがそのグローバル識別子と明確に関連付けられるように設計されることがあります。
itemid属性に指定されたURLの正確な意味は、使用される語彙によって異なります。
ここでは、特定の本について説明するアイテムの例です:
< dl itemscope
itemtype = "https://vocab.example.net/book"
itemid = "urn:isbn:0-330-34032-8" >
< dt > タイトル
< dd itemprop = "title" > The Reality Dysfunction
< dt > 著者
< dd itemprop = "author" > Peter F. Hamilton
< dt > 出版日
< dd >< time itemprop = "pubdate" datetime = "1996-01-26" > 1996年1月26日</ time >
</ dl >
この例では、「https://vocab.example.net/book」という語彙は、itemid属性が書籍のISBNを指すurn:形式のURLを受け取ることを定義しています。
このセクションは規範的ではありません。
マイクロデータを使用するということは、語彙を使用することを意味します。ある目的のためには、即席の語彙で十分です。別の目的では、語彙を設計する必要があります。可能な限り、既存の語彙を再利用することが推奨されます。これにより、コンテンツの再利用が容易になります。
新しい語彙を設計する際には、識別子はURLを使用して作成するか、プロパティの場合はプレーンな単語(ドットやコロンを含まない)として作成できます。URLの場合、著者が管理するページに対応する識別子のみを使用することで、他の語彙との競合を避けることができます。
たとえば、JonとAdamがそれぞれexample.comのhttps://example.com/~jon/...とhttps://example.com/~adam/...でコンテンツを書いている場合、それぞれ「https://example.com/~jon/name」と「https://example.com/~adam/name」という形式の識別子を選択することができます。
名前がプレーンな単語であるプロパティは、それらが意図されているタイプのコンテキスト内でのみ使用できます。URLを使用して名前が付けられたプロパティは、任意のタイプのアイテムで再利用することができます。アイテムにタイプがない場合、または別のアイテムの一部でない場合、そのプロパティの名前がプレーンな単語であれば、それはグローバルに一意であることを意図していないため、限定された用途のみに意図されています。一般的に、著者はグローバルに一意の名前(URL)を持つプロパティを使用するか、アイテムがタイプ付きであることを確認することが推奨されます。
ここでは、アイテムは「https://example.org/animals#cat」であり、プロパティの大部分はそのタイプのコンテキスト内で定義された単語として名前が付けられています。さらに、他の語彙から来た名前を持ついくつかの追加のプロパティもあります。
< section itemscope itemtype = "https://example.org/animals#cat" >
< h1 itemprop = "name https://example.com/fn" > Hedral</ h1 >
< p itemprop = "desc" > Hedral is a male American domestic
shorthair, with a fluffy < span itemprop = "https://example.com/color" > black</ span > fur with < span itemprop = "https://example.com/color" > white</ span > paws and belly.</ p >
< img itemprop = "img" src = "hedral.jpeg" alt = "" title = "Hedral, age 18 months" >
</ section >
この例では、1つのアイテムが「https://example.org/animals#cat」というタイプを持ち、次のプロパティを持っています。
| プロパティ | 値 |
| name | Hedral |
| https://example.com/fn | Hedral |
| desc | Hedral is a male American domestic shorthair, with a fluffy black fur with white paws and belly. |
| https://example.com/color | black |
| https://example.com/color | white |
| img | .../hedral.jpeg |
マイクロデータモデルは、アイテムと呼ばれる名前と値のペアのグループで構成されています。
各グループはアイテムと呼ばれます。各アイテムは、アイテムタイプ、グローバル識別子(アイテムタイプによって指定された語彙がグローバル識別子をサポートする場合)、および名前と値のペアのリストを持つことができます。名前と値のペアの各名前はプロパティと呼ばれ、各プロパティには1つ以上の値があります。各値は文字列であるか、それ自体が名前と値のペアのグループ(アイテム)です。名前は互いに順序付けられていませんが、特定の名前に複数の値がある場合、それらには相対的な順序があります。
すべての最新エンジンでサポートされています。
すべてのHTML要素には、itemscope属性を指定することができます。
itemscope属性はブール属性です。
itemscope属性が指定された要素は、新しいアイテム、つまり名前と値のペアのグループを作成します。
すべての最新エンジンでサポートされています。
itemscope属性を持つ要素には、itemtype属性を指定して、アイテムタイプを指定することができます。
指定された場合、itemtype属性の値は一意なスペース区切りトークンの順不同セットでなければならず、そのいずれもが他のトークンと同一であってはならず、各トークンは有効なURL文字列であり、絶対URLである必要があります。また、すべて同じ語彙を使用するように定義されている必要があります。属性の値には、少なくとも1つのトークンが含まれている必要があります。
アイテムのアイテムタイプは、要素のitemtype属性の値をASCII空白で分割して取得されたトークンです。itemtype属性が存在しないか、この方法で解析してもトークンが見つからない場合、そのアイテムにはアイテムタイプがないとされます。
アイテムタイプはすべて適用可能な仕様で定義されたタイプでなければならず、すべて同じ語彙を使用するように定義されていなければなりません。
その仕様で別途指定されていない限り、URLがアイテムタイプとして指定されている場合、自動的に参照されるべきではありません。
仕様によっては、アイテムタイプを参照して、ユーザーにヘルプ情報を提供するなどの定義がされている場合があります。実際、語彙の著者は指定されたURLに役立つ情報を提供することが奨励されています。
アイテムタイプは不透明な識別子であり、ユーザーエージェントは、未知のアイテムタイプを参照したり、それを分解したりして、それを使用するアイテムを処理する方法を決定することはできません。
itemtype属性は、itemscope属性が指定されていない要素には指定してはなりません。
アイテムは、アイテムタイプを持っているか、あるいは、型付きアイテムのプロパティの値である場合、型付きアイテムと呼ばれます。型付きアイテムに対する関連するタイプは、そのアイテムのアイテムタイプであり、もしアイテムタイプがなければ、それがプロパティの値であるアイテムの関連するタイプになります。
すべての最新エンジンでサポートされています。
itemscope属性と、アイテムのグローバル識別子をサポートすると定義された語彙を参照するitemtype属性を持つ要素には、itemid属性を指定して、そのアイテムのグローバル識別子を指定することができます。これにより、他のウェブページにあるアイテムと関連付けることができます。
指定された場合、itemid属性の値はスペースで囲まれる可能性のある有効なURLでなければなりません。
アイテムのグローバル識別子は、その要素のitemid属性の値であり、指定されている場合、その属性が指定されている要素のURLとして解析され、ノードドキュメントに関連付けられます。itemid属性が存在しない場合、または解析に失敗した場合、それにはグローバル識別子がないとされます。
itemid属性は、itemscope属性およびitemtype属性の両方が指定されていない要素には指定してはならず、また、語彙の仕様でアイテムのグローバル識別子をサポートしないと定義されているitemscope属性の要素には指定してはなりません。
グローバル識別子の正確な意味は、語彙の仕様によって決定されます。このような仕様は、同じグローバル識別子を持つ複数のアイテムが(同じページ上または異なるページ上で)存在することが許可されているかどうか、および同じIDを持つ複数のアイテムに関する処理ルールを規定する責任を負います。
すべての最新エンジンでサポートされています。
itemscope属性を持つ要素には、itemref属性を指定して、アイテムの名前と値のペアを見つけるためにクロールする追加の要素のリストを指定できます。
指定された場合、itemref属性の値は一意なスペース区切りトークンの順不同セットでなければならず、そのいずれもが他のトークンと同一であってはならず、同じツリー内の要素のIDで構成されている必要があります。
itemref属性は、itemscope属性が指定されていない要素には指定してはなりません。
itemref属性はマイクロデータモデルの一部ではありません。これは単に、データを注釈付けする際に、データが便利なツリー構造に従っていない場合に、著者を支援するための構文構造です。たとえば、各列が別個のアイテムを定義し、セルにプロパティを保持するように、テーブル内のデータにマークアップを付けることができます。
この例は、鉄道模型メーカーの製品を記述するために使用される簡単な語彙を示しています。この語彙には、次の5つのプロパティ名があります:
この語彙には、次の4つの定義されたアイテムタイプがあります:
この語彙を使用するアイテムには、製品が何であるかに応じて、これらのタイプのいずれかまたは複数を指定できます。
したがって、機関車は次のようにマークアップされる可能性があります:
< dl itemscope itemtype = "https://md.example.com/loco
https://md.example.com/lighting" >
< dt > Name:
< dd itemprop = "name" > Tank Locomotive (DB 80)
< dt > Product code:
< dd itemprop = "product-code" > 33041
< dt > Scale:
< dd itemprop = "scale" > HO
< dt > Digital:
< dd itemprop = "digital" > Delta
</ dl >
ポイントランタンの後付けキットは次のようにマークアップされる可能性があります:
< dl itemscope itemtype = "https://md.example.com/track
https://md.example.com/lighting" >
< dt > Name:
< dd itemprop = "name" > Turnout Lantern Kit
< dt > Product code:
< dd itemprop = "product-code" > 74470
< dt > Purpose:
< dd > For retrofitting 2 < span itemprop = "track-type" > C</ span > Track
turnouts. < meta itemprop = "scale" content = "HO" >
</ dl >
照明のない客車は次のようにマークアップされる可能性があります:
< dl itemscope itemtype = "https://md.example.com/passengers" >
< dt > Name:
< dd itemprop = "name" > Express Train Passenger Car (DB Am 203)
< dt > Product code:
< dd itemprop = "product-code" > 8710
< dt > Scale:
< dd itemprop = "scale" > Z
</ dl >
新しい語彙を作成する際には細心の注意が必要です。多くの場合、タイプに対して階層的なアプローチを取ることで、各アイテムが単一のタイプしか持たない語彙を作成することができ、これが管理するのに非常に簡単です。
itemprop 属性すべての現在のエンジンでサポートされています。
すべての HTML 要素 は、itemprop
属性を指定できます。これにより、1つ以上の プロパティ が 1つ以上の アイテム に追加されます(以下で定義)。
指定されている場合、itemprop
属性の値は、一意のスペースで区切られたトークンの順不同セットであり、そのどれもが他のトークンと
同一ではなく、追加される名前と値のペアの名前を表します。属性の値には少なくとも1つのトークンが必要です。
各トークンは次のいずれかでなければなりません:
定義されたプロパティ名 を導入する仕様は、そのようなプロパティ名が U+002E FULL STOP 文字(.)、U+003A COLON 文字(:)、および ASCII スペース を含まないことを保証する必要があります。
上記のルールは、URL以外の値に U+003A COLON 文字(:)を許可しないため、そうでなければ URL と区別できなくなるためです。U+002E FULL STOP 文字(.)を含む値は将来の拡張のために予約されています。 ASCII スペース は、そうでなければ値が複数のトークンとして解析されるため、禁止されています。
プロパティ が複数の アイテム に追加される場合、上記のトークンに関する要件は、個々の アイテム に個別に適用されます。
要素の プロパティ名 は、要素の itemprop
属性の値が
ASCII
スペースで分割された ときに含まれるトークンであり、順序が保持され、重複は削除されます(各名前の最初の出現のみが残ります)。
アイテム 内では、同じ名前のプロパティを除いて、プロパティは互いに順序付けられていません。同じ名前のプロパティは、アイテムの プロパティを定義するアルゴリズム によって与えられた順序で順序付けられています。
次の例では、「a」プロパティには「1」と「2」の値があり、その順序で です。ただし、「a」プロパティが「b」プロパティの前にあるかどうかは重要ではありません:
< div itemscope >
< p itemprop = "a" > 1</ p >
< p itemprop = "a" > 2</ p >
< p itemprop = "b" > テスト</ p >
</ div >
したがって、次のものと同等です:
< div itemscope >
< p itemprop = "b" > テスト</ p >
< p itemprop = "a" > 1</ p >
< p itemprop = "a" > 2</ p >
</ div >
次のものも同様です:
< div itemscope >
< p itemprop = "a" > 1</ p >
< p itemprop = "b" > テスト</ p >
< p itemprop = "a" > 2</ p >
</ div >
さらに次のものも同様です:
< div id = "x" >
< p itemprop = "a" > 1</ p >
</ div >
< div itemscope itemref = "x" >
< p itemprop = "b" > テスト</ p >
< p itemprop = "a" > 2</ p >
</ div >
itemprop
属性を持つ要素によって追加される名前と値のペアのプロパティ値は、以下のリストの最初に一致するケースに基づいて決定されます。
itemscope属性も持つ場合
値は、要素によって作成されたアイテムです。
meta要素である場合
値は、要素のcontent属性の値です。属性がない場合は空の文字列となります。
audio、embed、iframe、img、source、track、またはvideo要素である場合
値は、要素のsrc属性の値に基づいて、要素のノード文書に対してURLを
エンコード、パース、およびシリアライズした結果です。属性がない場合や結果が失敗した場合は空の文字列となります。
a、area、またはlink要素である場合
値は、要素のhref属性の値に基づいて、要素のノード文書に対してURLを
エンコード、パース、およびシリアライズした結果です。属性がない場合や結果が失敗した場合は空の文字列となります。
object要素である場合
値は、要素のdata属性の値に基づいて、要素のノード文書に対してURLを
エンコード、パース、およびシリアライズした結果です。属性がない場合や結果が失敗した場合は空の文字列となります。
data要素である場合
値は、要素のvalue属性の値です。属性がない場合は空の文字列となります。
meter要素である場合
値は、要素のvalue属性の値です。属性がない場合は空の文字列となります。
time要素である場合
値は要素のdatetime 値です。
値は要素の子孫テキストコンテンツです。
URL プロパティ要素は、a、area、
audio、embed、iframe、
img、link、
object、source、
track、およびvideo要素です。
プロパティの値が、その定義によって絶対 URLである場合、プロパティはURL プロパティ要素を使用して指定する必要があります。
これらの要件は、プロパティ値がたまたま URL の構文に一致するだけで適用されるわけではありません。プロパティが明示的にそのような値を取ると定義されている場合にのみ適用されます。
例えば、最初の月面着陸についての本が「mission:moon」と呼ばれることがあります。タイトルが文字列として定義されている語彙の「タイトル」プロパティは、たとえそれが URL のように見えても、
a
要素で指定されることを期待しません。一方、「URLのように見えるタイトルを持つ本」に関する(非常に限定された!)語彙があり、URL を取るように定義された「タイトル」プロパティがある場合、プロパティはa 要素(または他の URL プロパティ要素 のいずれか)で指定されることを期待します。
root要素によって定義されるアイテムのプロパティを見つけるために、ユーザーエージェントは以下の手順を実行する必要があります。これらの手順は、マイクロデータエラーをフラグするためにも使用されます。
results、memory、およびpendingという空の要素リストを作成します。
root要素をmemoryに追加します。
もしrootに子要素があれば、それらをpendingに追加します。
もしrootがitemref属性を持っている場合、そのitemref属性の値をASCII空白文字で分割します。その結果得られる各トークンIDに対して、rootのツリーにIDというIDを持つ要素が存在する場合、その最初の要素をpendingに追加します。
pendingが空でない間:
pendingから要素を取り出し、その要素をcurrentとします。
もしcurrentが既にmemoryに含まれている場合、マイクロデータエラーが発生し、続行します。
currentをmemoryに追加します。
もしcurrentがitemscope属性を持っていない場合、その子要素をすべてpendingに追加します。
もしcurrentがitemprop属性を持ち、かつ一つ以上のプロパティ名を持っている場合、currentをresultsに追加します。
resultsをツリー順で並べ替えます。
resultsを返します。
ドキュメントには、アルゴリズムによってマイクロデータエラーが見つかるアイテムが含まれていてはなりません。
アイテムは、その要素にitemprop属性が指定されていない場合、トップレベルのマイクロデータアイテムと呼ばれます。
itemref属性は、ドキュメント内のアイテムがサイクルを形成しないように設定されている必要があります。グラフを構成する際に、ドキュメント内の各アイテムをノードとして表し、アイテムのプロパティの値が別のアイテムである場合、そのプロパティを接続するエッジとして表します。
ドキュメントには、itemprop属性を持つ要素が含まれていてはなりません。それらがドキュメント内のいずれかのアイテムのプロパティとして見つからない場合です。
この例では、単一のライセンス文が2つの作品に適用されており、作品を表すアイテムからitemrefを使用しています:
<!DOCTYPE HTML>
< html lang = "en" >
< head >
< title > Photo gallery</ title >
</ head >
< body >
< h1 > My photos</ h1 >
< figure itemscope itemtype = "http://n.whatwg.org/work" itemref = "licenses" >
< img itemprop = "work" src = "images/house.jpeg" alt = "A white house, boarded up, sits in a forest." >
< figcaption itemprop = "title" > The house I found.</ figcaption >
</ figure >
< figure itemscope itemtype = "http://n.whatwg.org/work" itemref = "licenses" >
< img itemprop = "work" src = "images/mailbox.jpeg" alt = "Outside the house is a mailbox. It has a leaflet inside." >
< figcaption itemprop = "title" > The mailbox.</ figcaption >
</ figure >
< footer >
< p id = "licenses" > All images licensed under the < a itemprop = "license"
href = "http://www.opensource.org/licenses/mit-license.php" > MIT
license</ a > .</ p >
</ footer >
</ body >
</ html >
上記の結果、次のタイプ "http://n.whatwg.org/work" を持つ2つのアイテムが生成されます:
images/house.jpeg
http://www.opensource.org/licenses/mit-license.php
...そして、次のアイテム:
images/mailbox.jpeg
http://www.opensource.org/licenses/mit-license.php
現在、itemscope、itemprop、および他のマイクロデータ属性は、HTML要素のためにのみ定義されています。つまり、"itemscope"、"itemprop"などのリテラル名を持つ属性は、SVGなどの他の名前空間の要素ではマイクロデータの処理を引き起こしません。
したがって、次の例ではアイテムは1つだけで、2つではありません。
< p itemscope ></ p > <!-- これはアイテムです(プロパティもタイプもなし) -->
< svg itemscope ></ svg > <!-- これはアイテムではなく、単に無効な未知の属性を持つ SVG svg 要素です -->
このセクションの語彙は主に語彙がどのように指定されるかを示すことを目的としていますが、それ自体でも使用可能です。
項目タイプが http://microformats.org/profile/hcardであるアイテムは、個人または組織の連絡先情報を表します。
この語彙はアイテムのグローバル識別子をサポートしません。
以下は、このタイプの定義されたプロパティ名です。それらは、vCard Format Specification(vCard)およびその拡張機能で定義された語彙に基づいており、値の解釈方法に関する詳細はそこに記載されています。[RFC6350]
kindアイテムが表す連絡先の種類を説明します。
値は、次のいずれかに一致するテキストである必要があります。種類の文字列。
kindという名前の単一のプロパティが、http://microformats.org/profile/hcardタイプの各アイテム内に存在する場合があります。
fn個人または組織の名前に対応する書式化されたテキストを提供します。
値はテキストである必要があります。
fnという名前のプロパティが、http://microformats.org/profile/hcardタイプの各アイテム内に正確に1つ存在する必要があります。
n個人または組織の構造化された名前を提供します。
値は、family-name、given-name、additional-name、honorific-prefix、およびhonorific-suffixプロパティのそれぞれを0個以上持つアイテムである必要があります。
nという名前のプロパティが、http://microformats.org/profile/hcardタイプの各アイテム内に正確に1つ存在する必要があります。
family-name(n内)個人の姓、または組織のフルネームを提供します。
値はテキストである必要があります。
アイテムが値を形成するnプロパティ内に、family-nameという名前のプロパティが任意の数存在することができます。
given-name(n内)個人の名を提供します。
値はテキストである必要があります。
アイテムが値を形成するnプロパティ内に、given-nameという名前のプロパティが任意の数存在することができます。
additional-name(n内)個人の追加名を提供します。
値はテキストである必要があります。
アイテムが値を形成するnプロパティ内に、additional-nameという名前のプロパティが任意の数存在することができます。
honorific-prefix(n内)個人の敬称を提供します。
値はテキストである必要があります。
アイテムが値を形成するnプロパティ内に、honorific-prefixという名前のプロパティが任意の数存在することができます。
honorific-suffix(n内)個人の敬称を提供します。
値はテキストである必要があります。
アイテムが値を形成するnプロパティ内に、honorific-suffixという名前のプロパティが任意の数存在することができます。
nickname個人または組織のニックネームを提供します。
ニックネームとは、人、場所、物に属するものの代わりに、または追加して与えられる記述的な名前です。また、fnまたはnプロパティによって指定された正式な名前の親しみやすい形式を指定するためにも使用できます。
値はテキストである必要があります。
nicknameという名前のプロパティが、http://microformats.org/profile/hcardタイプの各アイテム内に任意の数存在することができます。
photo個人または組織の写真を提供します。
photoという名前のプロパティが、http://microformats.org/profile/hcardタイプの各アイテム内に任意の数存在することができます。
bday個人または組織の生年月日を提供します。
bdayという名前の単一のプロパティが、http://microformats.org/profile/hcardタイプの各アイテム内に存在する場合があります。
anniversary個人または組織の記念日を提供します。
anniversaryという名前の単一のプロパティが、http://microformats.org/profile/hcardタイプの各アイテム内に存在する場合があります。
sex個人の生物学的性別を提供します。
値は、F("女性")、M("男性")、N("なしまたは該当なし")、O("その他")、またはU("不明")のいずれかである必要があります。
sexという名前の単一のプロパティが、http://microformats.org/profile/hcardタイプの各アイテム内に存在する場合があります。
gender-identity個人の性自認を提供します。
値はテキストである必要があります。
gender-identityという名前の単一のプロパティが、http://microformats.org/profile/hcardタイプの各アイテム内に存在する場合があります。
adr個人または組織の配達先住所を提供します。
値はアイテムであり、0個以上のtype、post-office-box、extended-address、street-addressプロパティ、およびオプションでlocalityプロパティ、オプションでregionプロパティ、オプションでpostal-codeプロパティ、およびオプションでcountry-nameプロパティを持つ必要があります。
もし、typeプロパティが、アイテム内に存在せず、そのアイテムが値を形成するadrプロパティが、http://microformats.org/profile/hcardタイプのアイテム内に存在する場合、住所タイプ文字列としてworkが暗黙的に適用されます。
adrという名前のプロパティが、http://microformats.org/profile/hcardタイプの各アイテム内に任意の数存在することができます。
type(adr内)配達先住所の種類を提供します。
値は、次のいずれかに一致するテキストである必要があります。アドレスタイプ文字列。
アイテムが値を形成するadrプロパティ内に、typeという名前のプロパティが任意の数存在することができますが、各adrプロパティ内のアイテムには、異なる値ごとに1つだけtypeプロパティが存在する必要があります。
post-office-box(adr内)個人または組織の配達先住所の郵便私書箱部分を提供します。
値はテキストである必要があります。
アイテムが値を形成するadrプロパティ内に、post-office-boxという名前のプロパティが任意の数存在することができます。
vCardは著者にこのフィールドを使用しないよう強く勧めています。
extended-address(adr内)個人または組織の配達先住所の追加コンポーネントを提供します。
値はテキストである必要があります。
アイテムが値を形成するadrプロパティ内に、extended-addressという名前のプロパティが任意の数存在することができます。
vCardは著者にこのフィールドを使用しないよう強く勧めています。
street-address(adr内)個人または組織の配達先住所の街区部分を提供します。
値はテキストである必要があります。
アイテムが値を形成するadrプロパティ内に、street-addressという名前のプロパティが任意の数存在することができます。
locality(adr内)個人または組織の配達先住所の地域部分(例:市)を提供します。
値はテキストである必要があります。
localityという名前のプロパティが、http://microformats.org/profile/hcardタイプのアイテムが値を形成するadrプロパティ内に存在する場合があります。
region(adr内)個人または組織の配達先住所の地域部分(例:州または県)を提供します。
値はテキストである必要があります。
regionという名前のプロパティが、http://microformats.org/profile/hcardタイプのアイテムが値を形成するadrプロパティ内に存在する場合があります。
postal-code(adr内)個人または組織の配達先住所の郵便番号部分を提供します。
値はテキストである必要があります。
postal-codeという名前のプロパティが、http://microformats.org/profile/hcardタイプのアイテムが値を形成するadrプロパティ内に存在する場合があります。
country-name(adr内)個人または組織の配達先住所の国名部分を提供します。
値はテキストである必要があります。
country-nameという名前のプロパティが、http://microformats.org/profile/hcardタイプのアイテムが値を形成するadrプロパティ内に存在する場合があります。
tel個人または組織の電話番号を提供します。
値は、テキストであり、CCITTの仕様E.163およびX.121で定義された電話番号として解釈できるか、アイテムであり、0個以上のtypeプロパティと正確に1つのvalueプロパティを持つ必要があります。[E163] [X121]
もしtypeプロパティがhttp://microformats.org/profile/hcardタイプのアイテムの値を構成するtelプロパティ内に存在しない場合、またはその値がテキストである場合、電話タイプ文字列のvoiceが暗示されます。
telという名前のプロパティが、http://microformats.org/profile/hcardタイプの各アイテム内に任意の数存在することができます。
type(tel内)電話番号の種類を提供します。
値は、次のいずれかに一致するテキストである必要があります。電話タイプ文字列。
アイテムが値を形成するtelプロパティ内に、typeという名前のプロパティが任意の数存在することができますが、各telプロパティ内のアイテムには、異なる値ごとに1つだけtypeプロパティが存在する必要があります。
value(tel内)個人または組織の実際の電話番号を提供します。
値はテキストであり、CCITTの仕様E.163およびX.121で定義された電話番号として解釈できる必要があります。[E163][X121]
email個人または組織のメールアドレスを提供します。
値はテキストである必要があります。
emailという名前のプロパティが、http://microformats.org/profile/hcardタイプの各アイテム内に任意の数存在することができます。
impp個人または組織とのインスタントメッセージングおよびプレゼンスプロトコル通信のためのURLを提供します。
imppという名前のプロパティが、http://microformats.org/profile/hcardタイプの各アイテム内に任意の数存在することができます。
lang個人または組織が理解する言語を提供します。
値は有効なBCP 47言語タグである必要があります。[BCP47]
langという名前のプロパティが、http://microformats.org/profile/hcardタイプの各アイテム内に任意の数存在することができます。
tz個人または組織のタイムゾーンを提供します。
値はテキストであり、次の構文に一致する必要があります:
tzという名前のプロパティが、http://microformats.org/profile/hcardタイプの各アイテム内に任意の数存在することができます。
geo個人または組織の地理的位置を提供します。
値はテキストであり、次の構文に一致する必要があります:
アスタリスク(*)でマークされたオプションのコンポーネントは含める必要があり、それぞれ6桁である必要があります。
値は緯度と経度をその順序で指定します(すなわち「LAT LON」の順序)。経度は、グリニッジ子午線から東西に位置する場所をそれぞれ正または負の実数として表します。緯度は、赤道から南北に位置する場所をそれぞれ正または負の実数として表します。
geoという名前のプロパティが、http://microformats.org/profile/hcardタイプの各アイテム内に任意の数存在することができます。
title個人または組織の役職、機能的位置または職務を提供します。
値はテキストである必要があります。
titleという名前のプロパティが、http://microformats.org/profile/hcardタイプの各アイテム内に任意の数存在することができます。
role個人または組織の役割、職業、またはビジネスカテゴリを提供します。
値はテキストである必要があります。
roleという名前のプロパティが、http://microformats.org/profile/hcardタイプの各アイテム内に任意の数存在することができます。
logo個人または組織のロゴを提供します。
logoという名前のプロパティが、http://microformats.org/profile/hcardタイプの各アイテム内に任意の数存在することができます。
agent個人または組織を代表して行動する別の人物の連絡先情報を提供します。
値は、アイテムであり、タイプhttp://microformats.org/profile/hcardを持つか、または絶対URLであるか、テキストである必要があります。
agentという名前のプロパティが、http://microformats.org/profile/hcardタイプの各アイテム内に任意の数存在することができます。
org組織の名称および単位を提供します。
値は、テキストであるか、またはorganization-nameプロパティを1つ持ち、0個以上のorganization-unitプロパティを持つアイテムである必要があります。
orgという名前のプロパティが、http://microformats.org/profile/hcardタイプの各アイテム内に任意の数存在することができます。
organization-name(org内)組織の名称を提供します。
値はテキストである必要があります。
organization-nameという名前のプロパティが、アイテムが値を形成するorgプロパティ内に正確に1つ存在する必要があります。
organization-unit(org内)組織の単位名称を提供します。
値はテキストである必要があります。
organization-unitという名前のプロパティが、アイテムが値を形成するorgプロパティ内に任意の数存在することができます。
memberURLを提供し、グループのメンバーを表します。
memberという名前のプロパティが、http://microformats.org/profile/hcardタイプの各アイテム内に任意の数存在することができますが、アイテムにkindという名前のプロパティが存在し、その値が"group"である場合に限ります。
related他のエンティティとの関係を提供します。
値は1つのurlプロパティと1つのrelプロパティを持つアイテムである必要があります。
relatedという名前のプロパティが、http://microformats.org/profile/hcardタイプの各アイテム内に任意の数存在することができます。
url(related内)URLを提供し、関連するエンティティを表します。
rel(related内)エンティティと関連するエンティティとの関係を提供します。
値は、次のいずれかに一致するテキストである必要があります。関係文字列。
categories個人または組織が分類されうるカテゴリまたはタグの名前を提供します。
値はテキストである必要があります。
categoriesという名前のプロパティが、http://microformats.org/profile/hcardタイプの各アイテム内に任意の数存在することができます。
note個人または組織に関する補足情報やコメントを提供します。
値はテキストである必要があります。
noteという名前のプロパティが、http://microformats.org/profile/hcardタイプの各アイテム内に任意の数存在することができます。
rev連絡先情報の修正日と時間を提供します。
値はテキストであり、有効なグローバル日付時刻文字列である必要があります。
値は、情報の他のバージョンに対して現在の情報の修正を区別します。
revという名前のプロパティが、http://microformats.org/profile/hcardタイプの各アイテム内に任意の数存在することができます。
sound個人または組織に関連するサウンドファイルを提供します。
soundという名前のプロパティが、http://microformats.org/profile/hcardタイプの各アイテム内に任意の数存在することができます。
uid個人または組織に対応するグローバルに一意の識別子を提供します。
値はテキストである必要があります。
uidという名前の単一のプロパティが、http://microformats.org/profile/hcardタイプの各アイテム内に存在する場合があります。
url個人または組織に関連するURLを提供します。
urlという名前のプロパティが、http://microformats.org/profile/hcardタイプの各アイテム内に任意の数存在することができます。
種類文字列は以下の通りです:
individual
単一のエンティティを示します(例:個人)。
group
複数のエンティティを示します(例:メーリングリスト)。
org
個人以外の単一のエンティティを示します(例:会社)。
location
地理的な場所を示します(例:オフィスビル)。
住所タイプ文字列は以下の通りです:
home
居住地の配送先住所を示します。
work
勤務先の配送先住所を示します。
電話タイプ文字列は以下の通りです:
home
居住用電話番号を示します。
work
勤務先の電話番号を示します。
text
テキストメッセージ(SMS)をサポートする電話番号を示します。
voice
音声通話用の電話番号を示します。
fax
ファクシミリ電話番号を示します。
cell
携帯電話番号を示します。
video
ビデオ会議用の電話番号を示します。
pager
ポケベルデバイス用の電話番号を示します。
textphone
聴覚または発話に障害のある人向けの通信デバイスを示します。
関係性文字列は以下の通りです:
emergency
緊急連絡先。
agent
このエンティティに代わって行動する別のエンティティ。
XFNで定義されている意味を持ちます。[XFN]
ユーザーエージェントは、Document内のノードのリストnodesが与えられた場合、以下のアルゴリズムを実行して、これらのノードによって表されるvCardデータを抽出する必要があります(最初のvCardのみが返されます):
nodes内のノードのいずれも、アイテムであり、アイテムタイプがhttp://microformats.org/profile/hcardでない場合、vCardは存在しません。アルゴリズムを中止し、何も返さない。
nodeを、nodes内の最初のノードで、アイテムであり、アイテムタイプがhttp://microformats.org/profile/hcardであるものとします。
outputを空の文字列とします。
タイプが「BEGIN」で値が「VCARD」のvCardラインを追加して、outputに追加します。
タイプが「PROFILE」で値が「VCARD」のvCardラインを追加して、outputに追加します。
タイプが「VERSION」で値が「4.0」のvCardラインを追加して、outputに追加します。
タイプが「SOURCE」で、vCardテキスト文字列をエスケープした結果であるドキュメントのURLを値としてoutputに追加します。
title要素がnullでない場合、タイプが「NAME」で、vCardテキスト文字列をエスケープして得られた結果を値として、title要素の子孫テキストコンテンツからoutputに追加します。
sexを空の文字列とします。
gender-identityを空の文字列とします。
nodeのアイテムのプロパティである各要素elementについて、elementのプロパティ名にある各名前nameに対して、次のサブステップを実行します:
parametersを名前と値のペアの空のセットとします。
以下のリストから適切なサブステップのセットを実行します。これらのステップでvalueという変数が設定され、次のステップで使用されます。
nである場合
valueを空の文字列とします。
subitem内の最初のvCardサブプロパティを収集し、名前がfamily-nameである結果をvalueに追加します。
subitem内の最初のvCardサブプロパティを収集し、名前がgiven-nameである結果をvalueに追加します。
subitem内の最初のvCardサブプロパティを収集し、名前がadditional-nameである結果をvalueに追加します。
subitem内の最初のvCardサブプロパティを収集し、名前がhonorific-prefixである結果をvalueに追加します。
subitem内の最初のvCardサブプロパティを収集し、名前がhonorific-suffixである結果をvalueに追加します。
adrである場合
valueを空の文字列とします。
subitem内のvCardサブプロパティを収集し、名前がpost-office-boxである結果をvalueに追加します。
subitem内のvCardサブプロパティを収集し、名前がextended-addressである結果をvalueに追加します。
subitem内のvCardサブプロパティを収集し、名前がstreet-addressである結果をvalueに追加します。
subitem内の最初のvCardサブプロパティを収集し、名前がlocalityである結果をvalueに追加します。
subitem内の最初のvCardサブプロパティを収集し、名前がregionである結果をvalueに追加します。
subitem内の最初のvCardサブプロパティを収集し、名前がpostal-codeである結果をvalueに追加します。
subitem内の最初のvCardサブプロパティを収集し、名前がcountry-nameである結果をvalueに追加します。
subitemに「type」という名前のプロパティが存在し、その最初のプロパティが値を持ち、かつその値がアイテムでなく、その値がASCII英数字のみで構成されている場合、そのプロパティのvalueを値として「TYPE」という名前のパラメータをparametersに追加します。
orgである場合
valueを空の文字列とします。
subitem内の最初のvCardサブプロパティを収集し、名前がorganization-nameである結果をvalueに追加します。
subitemに「organization-unit」という名前のプロパティが存在する場合、以下の手順を実行します:
U+003B セミコロン文字(;)をvalueに追加します。
プロパティの値によって与えられるvCardテキスト文字列をエスケープした結果をvalueに追加します。
http://microformats.org/profile/hcardであり、nameがrelatedである場合
valueを空の文字列とします。
subitemに「url」という名前のプロパティが存在し、その要素がURLプロパティ要素である場合、最初のプロパティの値によって与えられるvCardテキスト文字列をエスケープした結果をvalueに追加し、「VALUE」という名前のパラメータを「URI」という値でparametersに追加します。
subitemに「rel」という名前のプロパティが存在し、その最初のプロパティが値を持ち、かつその値がアイテムでなく、その値がASCII英数字のみで構成されている場合、そのプロパティのvalueを値として「RELATION」という名前のパラメータをparametersに追加します。
valueを、subitem内の最初のvCardサブプロパティを収集し、名前がvalueである結果とします。
subitemに「type」という名前のプロパティが存在し、その最初のプロパティが値を持ち、かつその値がアイテムでなく、その値がASCII英数字のみで構成されている場合、そのプロパティのvalueを値として「TYPE」という名前のパラメータをparametersに追加します。
sexである場合
これが最初に見つかったプロパティである場合、プロパティの値をsexに設定します。
gender-identityである場合
これが最初に見つかったプロパティである場合、プロパティの値をgender-identityに設定します。
プロパティの値をvalueとします。
elementがURLプロパティ要素のいずれかである場合、「VALUE」という名前のパラメータと「URI」という値をparametersに追加します。
それ以外の場合、nameがbdayまたはanniversaryであり、valueが有効な日付文字列である場合、「VALUE」という名前のパラメータと「DATE」という値をparametersに追加します。
それ以外の場合、nameがrevであり、valueが有効なグローバル日付と時間文字列である場合、「VALUE」という名前のパラメータと「DATE-TIME」という値をparametersに追加します。
value内のすべてのU+005C リバースソリッドス(\)文字の前に、もう一つのU+005C リバースソリッドス(\)文字を追加します。
value内のすべてのU+002C コンマ(,)文字の前にU+005C リバースソリッドス(\)文字を追加します。
nameがgeoでない場合、value内のすべてのU+003B
セミコロン文字(;)の前にU+005C リバースソリッドス(\)文字を追加します。
value内のすべてのU+000D キャリッジリターンU+000A ラインフィード文字ペア(CRLF)を、U+005C リバースソリッドス(\)文字とU+006E ラテン小文字(n)で置き換えます。
value内の残りのU+000D キャリッジリターン(CR)またはU+000A ラインフィード(LF)文字を、U+005C リバースソリッドス(\)文字とU+006E ラテン小文字(n)で置き換えます。
vCardラインを追加し、nameというタイプ、parametersというパラメータ、およびvalueという値をoutputに追加します。
sexまたはgender-identityのいずれかに空でない値が含まれている場合、vCardラインを追加し、タイプ「GENDER」と値をsex、U+003B
セミコロン文字(;)、およびgender-identityの連結で構成されたものをoutputに追加します。
タイプが「END」で値が「VCARD」のvCardラインを追加して、outputに追加します。
上記のアルゴリズムで、ユーザーエージェントがtypeと、必要に応じていくつかのパラメータ、およびvalueから成るvCardラインを文字列outputに追加するよう指示された場合、次の手順を実行する必要があります:
lineを空の文字列にします。
typeを、ASCII大文字に変換した上でlineに追加します。
パラメータが存在する場合、それらが追加された順に次のサブステップを実行します:
lineにU+003B セミコロン文字(;)を追加します。
パラメータの名前をlineに追加します。
lineにU+003D イコール記号(=)を追加します。
パラメータの値をlineに追加します。
lineにU+003A コロン文字(:)を追加します。
valueをlineに追加します。
maximum lengthを75に設定します。
lineのコードポイント長がmaximum lengthを超える場合、次の手順を実行します:
lineの最初のmaximum lengthコードポイントをoutputに追加します。
lineの最初のmaximum lengthコードポイントを削除します。
outputにU+000D キャリッジリターン(CR)文字を追加します。
outputにU+000A ラインフィード(LF)文字を追加します。
outputにU+0020 スペース文字を追加します。
maximum lengthを74に設定します。
line(の残りの部分)をoutputに追加します。
outputにU+000D キャリッジリターン(CR)文字を追加します。
outputにU+000A ラインフィード(LF)文字を追加します。
上記の手順で、ユーザーエージェントがsubitem内のsubnameという名前のvCardサブプロパティを収集する結果を得るよう指示された場合、次の手順を実行する必要があります:
valueを空の文字列とします。
subitem内のsubnameという名前のプロパティごとに、次のサブステップを実行します:
このプロパティがsubitem内で最初のsubnameという名前のプロパティでない場合(前のステップでスキップされたものは無視)、valueにU+002C コンマ文字(,)を追加します。
プロパティの値によって与えられるvCardテキスト文字列をエスケープした結果をvalueに追加します。
valueを返します。
上記の手順で、ユーザーエージェントがsubitem内のsubnameという名前の最初のvCardサブプロパティを収集する結果を取得するよう指示された場合、次の手順を実行する必要があります:
subitem内にsubnameという名前のプロパティが存在しない場合、空の文字列を返します。
subitem内の最初のsubnameという名前のプロパティの値によって与えられるvCardテキスト文字列をエスケープした結果を返します。
上記のアルゴリズムで、ユーザーエージェントがvalueをvCardテキスト文字列をエスケープするよう指示された場合、ユーザーエージェントは次の手順を実行する必要があります:
value内のすべてのU+005C リバースソリッドス(\)文字の前に、もう一つのU+005C リバースソリッドス(\)文字を追加します。
value内のすべてのU+002C コンマ(,)文字の前にU+005C リバースソリッドス(\)文字を追加します。
value内のすべてのU+003B セミコロン(;)文字の前にU+005C リバースソリッドス(\)文字を追加します。
value内のすべてのU+000D キャリッジリターンとU+000A ラインフィードの文字ペア(CRLF)を、U+005C リバースソリッドス(\)文字とU+006E ラテン小文字n(n)に置き換えます。
value内の残りのすべてのU+000D キャリッジリターン(CR)またはU+000A ラインフィード(LF)文字を、U+005C リバースソリッドス(\)文字とU+006E ラテン小文字n(n)に置き換えます。
変更されたvalueを返します。
このアルゴリズムは、入力がhttp://microformats.org/profile/hcardのアイテムタイプおよび定義されたプロパティ名に記載されたルールに準拠していない場合、無効なvCard出力を生成する可能性があります。
このセクションは規範的ではありません。
以下は、架空のキャラクター「ジャック・バウアー」の長い例のvCardです:
< section id = "jack" itemscope itemtype = "http://microformats.org/profile/hcard" >
< h1 itemprop = "fn" >
< span itemprop = "n" itemscope >
< span itemprop = "given-name" > Jack</ span >
< span itemprop = "family-name" > Bauer</ span >
</ span >
</ h1 >
< img itemprop = "photo" alt = "" src = "jack-bauer.jpg" >
< p itemprop = "org" itemscope >
< span itemprop = "organization-name" > Counter-Terrorist Unit</ span >
(< span itemprop = "organization-unit" > Los Angeles Division</ span > )
</ p >
< p >
< span itemprop = "adr" itemscope >
< span itemprop = "street-address" > 10201 W. Pico Blvd.</ span >< br >
< span itemprop = "locality" > Los Angeles</ span > ,
< span itemprop = "region" > CA</ span >
< span itemprop = "postal-code" > 90064</ span >< br >
< span itemprop = "country-name" > United States</ span >< br >
</ span >
< span itemprop = "geo" > 34.052339;-118.410623</ span >
</ p >
< h2 > 様々な連絡方法</ h2 >
< ul >
< li itemprop = "tel" itemscope >
< span itemprop = "value" > +1 (310) 597 3781</ span > < span itemprop = "type" > work</ span >
< meta itemprop = "type" content = "voice" >
</ li >
< li >< a itemprop = "url" href = "https://en.wikipedia.org/wiki/Jack_Bauer" > 私はウィキペディアにいます</ a >
ウィキペディアのユーザー会話ページにメッセージを残せます。</ li >
< li >< a itemprop = "url" href = "http://www.jackbauerfacts.com/" > Jack Bauer Facts</ a ></ li >
< li itemprop = "email" >< a href = "mailto:j.bauer@la.ctu.gov.invalid" > j.bauer@la.ctu.gov.invalid</ a ></ li >
< li itemprop = "tel" itemscope >
< span itemprop = "value" > +1 (310) 555 3781</ span > < span >
< meta itemprop = "type" content = "cell" > 携帯電話</ span >
</ li >
</ ul >
< ins datetime = "2008-07-20 21:00:00+01:00" >
< meta itemprop = "rev" content = "2008-07-20 21:00:00+01:00" >
< p itemprop = "tel" itemscope >< strong > 更新!</ strong >
私の新しい< span itemprop = "type" > 自宅</ span > の電話番号は
< span itemprop = "value" > 01632 960 123</ span > 。</ p >
</ ins >
</ section >
不思議な行の折り返しは、マイクロデータでは改行が意味を持つためです。例えば、vCard形式に変換する際には、改行が保持されます。
この例は、住所の2つの街区部分を含むサイトの連絡先詳細(address要素を使用)を示しています:
< address itemscope itemtype = "http://microformats.org/profile/hcard" >
< strong itemprop = "fn" >< span itemprop = "n" itemscope >< span itemprop = "given-name" > Alfred</ span >
< span itemprop = "family-name" > Person</ span ></ span ></ strong > < br >
< span itemprop = "adr" itemscope >
< span itemprop = "street-address" > 1600 Amphitheatre Parkway</ span > < br >
< span itemprop = "street-address" > Building 43, Second Floor</ span > < br >
< span itemprop = "locality" > Mountain View</ span > ,
< span itemprop = "region" > CA</ span > < span itemprop = "postal-code" > 94043</ span >
</ span >
</ address >
vCard語彙を使用して、人々の名前のみをマークアップすることもできます:
< span itemscope itemtype = "http://microformats.org/profile/hcard"
>< span itemprop = fn >< span itemprop = "n" itemscope >< span itemprop = "given-name"
> George</ span > < span itemprop = "family-name" > Washington</ span ></ span
></ span ></ span >
これにより、「fn」という名前と「ジョージ・ワシントン」という値を持つ1つのアイテムと、「n」という名前とその値として2番目のアイテムを持つ2つの名前-値ペアが作成されます。2番目のアイテムには、「given-name」と「family-name」という名前と「ジョージ」と「ワシントン」という値を持つ2つの名前-値ペアがあります。これは、次のvCardにマップされるように定義されています:
BEGIN:VCARD PROFILE:VCARD VERSION:4.0 SOURCE:document's address FN:George Washington N:Washington;George;;; END:VCARD
アイテムタイプ http://microformats.org/profile/hcalendar#vevent を持つアイテムは、イベントを表します。
この語彙はアイテムに対するグローバル識別子をサポートしていません。
以下は、このタイプの定義済みのプロパティ名です。それらは、インターネットカレンダーおよびスケジューリングコアオブジェクト仕様(iCalendar)で定義された語彙に基づいており、値の解釈方法に関する詳細はそこで確認できます。[RFC5545]
ここで使用されるのは、iCalendar 語彙のうちイベントに関連する部分のみです。この語彙は完全なiCalendarインスタンスを表現することはできません。
attach
イベントに関連するドキュメントのアドレスを示します。
attachという名前のプロパティは、http://microformats.org/profile/hcalendar#veventというタイプのアイテム内に、任意の数だけ存在させることができます。
categories
イベントが分類されるカテゴリやタグの名前を示します。
値はテキストでなければなりません。
categoriesという名前のプロパティは、http://microformats.org/profile/hcalendar#veventというタイプのアイテム内に、任意の数だけ存在させることができます。
class
イベントに関する情報のアクセス分類を示します。
値は次のいずれかのテキストでなければなりません:
public
private
confidential
これは単なる助言であり、機密保持の手段としては考慮されません。
classという名前のプロパティは、http://microformats.org/profile/hcalendar#veventというタイプのアイテム内に1つだけ存在させることができます。
comment
イベントに関するコメントを示します。
値はテキストでなければなりません。
commentという名前のプロパティは、http://microformats.org/profile/hcalendar#veventというタイプのアイテム内に、任意の数だけ存在させることができます。
description
イベントの詳細な説明を示します。
値はテキストでなければなりません。
descriptionという名前のプロパティは、http://microformats.org/profile/hcalendar#veventというタイプのアイテム内に1つだけ存在させることができます。
geo
イベントの地理的位置を示します。
値はテキストでなければならず、次の構文に一致する必要があります:
アスタリスク(*)で示されたオプションの要素は含めるべきであり、各要素には6桁の数字が必要です。
値は、緯度と経度(つまり「LAT LON」の順序)を10進数度で指定します。経度は、グリニッジ子午線の東と西の位置を、それぞれ正または負の実数で表します。緯度は、赤道の北と南の位置を、それぞれ正または負の実数で表します。
geoという名前のプロパティは、http://microformats.org/profile/hcalendar#veventというタイプのアイテム内に1つだけ存在させることができます。
location
イベントの場所を示します。
値はテキストでなければなりません。
locationという名前のプロパティは、http://microformats.org/profile/hcalendar#veventというタイプのアイテム内に1つだけ存在させることができます。
resources
イベントに必要なリソースを示します。
値はテキストでなければなりません。
resourcesという名前のプロパティは、http://microformats.org/profile/hcalendar#veventというタイプのアイテム内に、任意の数だけ存在させることができます。
status
イベントの確認状況を示します。
値は次のいずれかのテキストでなければなりません:
tentative
confirmed
canceled
statusという名前のプロパティは、http://microformats.org/profile/hcalendar#veventというタイプのアイテム内に1つだけ存在させることができます。
summary
イベントの簡単な要約を示します。
値はテキストでなければなりません。
ユーザーエージェントは、値内のU+000A LINE FEED (LF)文字を使用時にU+0020 SPACE文字に置き換える必要があります。
summaryという名前のプロパティは、http://microformats.org/profile/hcalendar#veventというタイプのアイテム内に1つだけ存在させることができます。
dtend
イベントが終了する日時を示します。
dtendという名前のプロパティが、アイテム内に存在し、dtstartという名前のプロパティの値が有効な日付文字列である場合、値は、同様に有効な日付文字列でなければなりません。それ以外の場合、プロパティの値は、有効なグローバル日付と時刻文字列でなければなりません。
いずれの場合も、値は同じアイテムのdtstartプロパティの値よりも後の時刻でなければなりません。
dtendプロパティで示される時刻は、包括的なものではありません。したがって、1日だけのイベントの場合、dtendプロパティの値はイベント終了日の翌日になります。
dtendという名前のプロパティは、http://microformats.org/profile/hcalendar#veventというタイプのアイテム内に1つだけ存在させることができます。ただし、そのhttp://microformats.org/profile/hcalendar#veventには、durationという名前のプロパティが存在しない限りです。
dtstart
イベントが開始される日時を示します。
値は、有効な日付文字列または有効なグローバル日付と時刻文字列のいずれかでなければなりません。
dtstartという名前のプロパティは、http://microformats.org/profile/hcalendar#veventというタイプのアイテム内に1つだけ存在しなければなりません。
duration
イベントの期間を示します。
値は、有効なvevent期間文字列でなければなりません。
表現される期間は、値内の整数によって表される全期間の合計です。
durationという名前のプロパティは、http://microformats.org/profile/hcalendar#veventというタイプのアイテム内に1つだけ存在させることができます。ただし、そのhttp://microformats.org/profile/hcalendar#veventには、dtendという名前のプロパティが存在しない限りです。
transp
フリービジータイム検索の目的で、イベントがカレンダー上で時間を消費すると見なされるかどうかを示します。
値は、次のいずれかのテキストでなければなりません:
opaque
transparent
transpという名前のプロパティは、http://microformats.org/profile/hcalendar#veventというタイプのアイテム内に1つだけ存在させることができます。
contact
イベントの連絡先情報を示します。
値はテキストでなければなりません。
contactという名前のプロパティは、http://microformats.org/profile/hcalendar#veventというタイプのアイテム内に、任意の数だけ存在させることができます。
url
イベントのURLを示します。
urlという名前のプロパティは、http://microformats.org/profile/hcalendar#veventというタイプのアイテム内に1つだけ存在させることができます。
uid
イベントに対応するグローバルに一意の識別子を示します。
値はテキストでなければなりません。
uidという名前のプロパティは、http://microformats.org/profile/hcalendar#veventというタイプのアイテム内に1つだけ存在させることができます。
exdate
繰り返しルールにもかかわらず、イベントが発生しない日時を示します。
値は、有効な日付文字列または有効なグローバル日付と時刻文字列のいずれかでなければなりません。
exdateという名前のプロパティは、http://microformats.org/profile/hcalendar#veventというタイプのアイテム内に、任意の数だけ存在させることができます。
rdate
イベントが繰り返される日時を示します。
値は、次のいずれかでなければなりません:
rdateという名前のプロパティは、http://microformats.org/profile/hcalendar#veventというタイプのアイテム内に、任意の数だけ存在させることができます。
rrule
イベントが発生する日時を見つけるためのルールを示します。
値は、iCalendarで定義されたRECUR値タイプに一致するテキストでなければなりません。[RFC5545]
rruleという名前のプロパティは、http://microformats.org/profile/hcalendar#veventというタイプのアイテム内に1つだけ存在させることができます。
created
イベント情報が最初にカレンダーシステムに作成された日時を示します。
値は有効なグローバル日付と時刻文字列でなければなりません。
createdという名前のプロパティは、http://microformats.org/profile/hcalendar#veventというタイプのアイテム内に1つだけ存在させることができます。
last-modified
イベント情報が最後にカレンダーシステムで修正された日時を示します。
値は有効なグローバル日付と時刻文字列でなければなりません。
last-modifiedという名前のプロパティは、http://microformats.org/profile/hcalendar#veventというタイプのアイテム内に1つだけ存在させることができます。
sequence
イベント情報のリビジョン番号を示します。
sequenceという名前のプロパティは、http://microformats.org/profile/hcalendar#veventというタイプのアイテム内に1つだけ存在させることができます。
文字列が次のパターンに一致する場合、その文字列は有効なvevent期間文字列です:
U+0050 LATIN CAPITAL LETTER P 文字 (P)。
次のいずれか:
nodes内のノードのリストがドキュメントにある場合、ユーザーエージェントは以下のアルゴリズムを実行して、これらのノードによって表されるvEventデータを抽出しなければなりません:
nodes内のいずれのノードもhttp://microformats.org/profile/hcalendar#veventタイプのアイテムでない場合、vEventデータはありません。アルゴリズムを中止し、何も返さないでください。
outputを空の文字列とします。
outputに「BEGIN」タイプと「VCALENDAR」値を持つiCalendar行を追加します。
outputにユーザーエージェントを表すユーザーエージェント固有の文字列に等しい値を持つ「PRODID」タイプのiCalendar行を追加します。
outputに「VERSION」タイプと「2.0」値を持つiCalendar行を追加します。
nodes内で、http://microformats.org/profile/hcalendar#veventタイプのアイテムであるノードnodeごとに、次の手順を実行します:
outputに「BEGIN」タイプと「VEVENT」値を持つiCalendar行を追加します。
現在の日付と時刻を表すiCalendar DATE-TIME文字列を持つ「DTSTAMP」タイプのiCalendar行を追加し、outputに「VALUE=DATE-TIME」という注釈を付けます。[RFC5545]
nodeのプロパティである要素elementごとに: elementのプロパティ名にある名前nameごとに、次のリストから適切なサブステップセットを実行します。
プロパティをスキップします。
dtendである場合
dtstartである場合
exdateである場合
rdateである場合
createdである場合
last-modifiedである場合
プロパティの値から、すべてのU+002D HYPHEN-MINUS (-)およびU+003A COLON (:)文字を取り除いた結果をvalueとします。
プロパティの値が有効な日付文字列である場合、nameタイプとvalue値を持ち、「VALUE=DATE」という注釈を付けたiCalendar行をoutputに追加します。
それ以外の場合、プロパティの値が有効なグローバル日付と時刻文字列である場合、nameタイプとvalue値を持ち、「VALUE=DATE-TIME」という注釈を付けたiCalendar行をoutputに追加します。
それ以外の場合、プロパティをスキップします。
nameタイプとプロパティの値を持つiCalendar行をoutputに追加します。
outputに「END」タイプと「VEVENT」値を持つiCalendar行を追加します。
outputに「END」タイプと「VCALENDAR」値を持つiCalendar行を追加します。
上記のアルゴリズムで、ユーザーエージェントがiCalendar行を追加し、type、value、およびオプションの注釈で構成される行を文字列outputに追加する場合、次の手順を実行しなければなりません:
lineを空の文字列とします。
typeをASCII大文字に変換し、lineに追加します。
注釈がある場合:
lineにU+003B SEMICOLON文字 (;)を追加します。
注釈をlineに追加します。
lineにU+003A COLON文字 (:)を追加します。
value内のすべてのU+005C REVERSE SOLIDUS文字 (\)の前に、もう1つのU+005C REVERSE SOLIDUS文字 (\)を追加します。
value内のすべてのU+002C COMMA文字 (,)の前にU+005C REVERSE SOLIDUS文字 (\)を追加します。
value内のすべてのU+003B SEMICOLON文字 (;)の前にU+005C REVERSE SOLIDUS文字 (\)を追加します。
value内のすべてのU+000D CARRIAGE RETURN U+000A LINE FEED文字ペア (CRLF)を、U+005C REVERSE SOLIDUS文字 (\)とその後に続くU+006E LATIN SMALL LETTER N文字 (n)に置き換えます。
value内の残りのU+000D CARRIAGE RETURN (CR)またはU+000A LINE FEED (LF)文字を、U+005C REVERSE SOLIDUS文字 (\)とその後に続くU+006E LATIN SMALL LETTER N文字 (n)に置き換えます。
valueをlineに追加します。
maximum lengthを75とします。
lineのコードポイントの長さがmaximum lengthを超える間:
lineの最初のmaximum lengthコードポイントをoutputに追加します。
lineの最初のmaximum lengthコードポイントを削除します。
outputにU+000D CARRIAGE RETURN文字 (CR)を追加します。
outputにU+000A LINE FEED文字 (LF)を追加します。
outputにU+0020 SPACE文字を追加します。
maximum lengthを74に設定します。
(残りの)lineをoutputに追加します。
outputにU+000D CARRIAGE RETURN文字 (CR)を追加します。
outputにU+000A LINE FEED文字 (LF)を追加します。
このアルゴリズムは、入力がhttp://microformats.org/profile/hcalendar#veventのアイテムタイプおよび定義済みプロパティ名のルールに準拠していない場合、無効なiCalendar出力を生成することがあります。
このセクションは規範的ではありません。
ここに、vEvent 語彙を使用してイベントをマークアップするページの例があります:
< body itemscope itemtype = "http://microformats.org/profile/hcalendar#vevent" >
...
< h1 itemprop = "summary" > ブルーズデイ・チューズデイ: マネー・ロード</ h1 >
...
< time itemprop = "dtstart" datetime = "2009-05-05T19:00:00Z" > 5月5日 @ 7pm</ time >
(until < time itemprop = "dtend" datetime = "2009-05-05T21:00:00Z" > 9pm</ time > )
...
< a href = "http://livebrum.co.uk/2009/05/05/bluesday-tuesday-money-road" rel = "bookmark" itemprop = "url" > このページへのリンク</ a >
...
< p > 場所: < span itemprop = "location" > The RoadHouse</ span ></ p >
...
< p >< input type = button value = "カレンダーに追加" onclick = "location = getCalendar(this)" ></ p >
...
< meta itemprop = "description" content = "via livebrum.co.uk" >
</ body >
getCalendar()関数は読者への練習問題として残しておきます。
同じページは、ブログにコピー&ペーストするために次のようなマークアップを提供することもできます:
< div itemscope itemtype = "http://microformats.org/profile/hcalendar#vevent" >
< p > 私は
< strong itemprop = "summary" > ブルーズデイ・チューズデイ: マネー・ロード</ strong > に行きます,
< time itemprop = "dtstart" datetime = "2009-05-05T19:00:00Z" > 5月5日 @ 7pm</ time >
から < time itemprop = "dtend" datetime = "2009-05-05T21:00:00Z" > 9pm</ time > まで,
< span itemprop = "location" > The RoadHouse</ span > で!</ p >
< p >< a href = "http://livebrum.co.uk/2009/05/05/bluesday-tuesday-money-road" itemprop = "url" > このイベントをlivebrum.co.ukで見る</ a > .</ p >
< meta itemprop = "description" content = "via livebrum.co.uk" >
</ div >
アイテムタイプ http://n.whatwg.org/workを持つアイテムは、作品(例:記事、画像、ビデオ、曲など)を表します。このタイプは主に、著者が作品のライセンス情報を含めることを可能にするために意図されています。
以下は、このタイプの定義されたプロパティ名です。
work
説明されている作品を識別します。
「work」という名前のプロパティは、http://n.whatwg.org/workというタイプのアイテム内に正確に1つ存在しなければなりません。
title
作品の名前を指定します。
「title」という名前のプロパティは、http://n.whatwg.org/workというタイプのアイテム内に1つだけ存在させることができます。
author
作品の著者または作成者の名前または連絡先情報を指定します。
値は、http://microformats.org/profile/hcardというタイプのアイテムか、テキストでなければなりません。
「author」という名前のプロパティは、http://n.whatwg.org/workというタイプのアイテム内に任意の数だけ存在させることができます。
license
作品が利用可能なライセンスの1つを識別します。
「license」という名前のプロパティは、http://n.whatwg.org/workというタイプのアイテム内に任意の数だけ存在させることができます。
このセクションは規範的ではありません。
この例は、クリエイティブ・コモンズ 表示 - 継承 4.0 国際ライセンスとMITライセンスの両方でライセンスされているMy Pondというタイトルの埋め込み画像を示しています。
< figure itemscope itemtype = "http://n.whatwg.org/work" >
< img itemprop = "work" src = "mypond.jpeg" >
< figcaption >
< p >< cite itemprop = "title" > My Pond</ cite ></ p >
< p >< small > 以下のライセンスに基づいてライセンスされています: < a itemprop = "license"
href = "https://creativecommons.org/licenses/by-sa/4.0/" > クリエイティブ・コモンズ 表示 - 継承 4.0 国際ライセンス</ a >
と < a itemprop = "license"
href = "http://www.opensource.org/licenses/mit-license.php" > MIT
ライセンス</ a > 。</ small >
</ figcaption >
</ figure >
ドキュメント内のnodesリストを前提として、ユーザーエージェントは次のアルゴリズムを実行して、それらのノードからマイクロデータを抽出してJSON形式に変換しなければなりません。
resultを空のオブジェクトとします。
itemsを空の配列とします。
nodes内の各nodeについて、要素がトップレベルのマイクロデータアイテムであるかを確認し、そうであれば、その要素のオブジェクトを取得し、itemsに追加します。
resultにitemsという名前のエントリを追加し、その値を配列itemsにします。
最も短い方法で(トークン間の空白をなくし、数値に不要なゼロを含めず、文字列の中で専用のエスケープシーケンスを持たない文字にのみUnicodeエスケープを使用する)resultをJSONにシリアル化して返します。また、適切な場合は、小文字の「e」を数値表現に使用します。[JSON]
このアルゴリズムは、配列を返す代わりに、単一のプロパティを持つオブジェクトを返すので、必要に応じて将来的にアルゴリズムを拡張することが可能です。
ユーザーエージェントがアイテムitemのためにオブジェクトを取得する場合、オプションでmemory要素のリストと共に、次のサブステップを実行しなければなりません。
resultを空のオブジェクトとします。
アルゴリズムにmemoryが渡されなかった場合、memoryを空のリストとします。
itemをmemoryに追加します。
itemにアイテムタイプがある場合、resultにtypeという名前のエントリを追加し、その値をitemのアイテムタイプの配列にします。
itemにグローバル識別子がある場合、resultにidという名前のエントリを追加し、その値をitemのグローバル識別子にします。
propertiesを空のオブジェクトとします。
1つ以上のプロパティ名を持ち、itemのプロパティの1つであるelementごとに、以下のサブステップを実行します。
elementのプロパティ値をvalueとします。
valueがアイテムの場合、valueがmemoryに含まれている場合、valueを「ERROR」という文字列にします。それ以外の場合は、memoryのコピーを渡してvalueのためにオブジェクトを取得し、それから返されたオブジェクトにvalueを置き換えます。
elementのプロパティ名の各nameについて、以下のサブステップを実行します。
propertiesにnameという名前のエントリがない場合、その名前のエントリをpropertiesに追加し、その値を空の配列とします。
propertiesのnameという名前のエントリにvalueを追加します。
resultにpropertiesという名前のエントリを追加し、その値をオブジェクトpropertiesにします。
resultを返します。
例えば、次のようなマークアップがあります。
<!DOCTYPE HTML>
< html lang = "en" >
< title > My Blog</ title >
< article itemscope itemtype = "http://schema.org/BlogPosting" >
< header >
< h1 itemprop = "headline" > Progress report</ h1 >
< p >< time itemprop = "datePublished" datetime = "2013-08-29" > today</ time ></ p >
< link itemprop = "url" href = "?comments=0" >
</ header >
< p > All in all, he's doing well with his swim lessons. The biggest thing was he had trouble
putting his head in, but we got it down.</ p >
< section >
< h1 > Comments</ h1 >
< article itemprop = "comment" itemscope itemtype = "http://schema.org/UserComments" id = "c1" >
< link itemprop = "url" href = "#c1" >
< footer >
< p > Posted by: < span itemprop = "creator" itemscope itemtype = "http://schema.org/Person" >
< span itemprop = "name" > Greg</ span >
</ span ></ p >
< p >< time itemprop = "commentTime" datetime = "2013-08-29" > 15 minutes ago</ time ></ p >
</ footer >
< p > Ha!</ p >
</ article >
< article itemprop = "comment" itemscope itemtype = "http://schema.org/UserComments" id = "c2" >
< link itemprop = "url" href = "#c2" >
< footer >
< p > Posted by: < span itemprop = "creator" itemscope itemtype = "http://schema.org/Person" >
< span itemprop = "name" > Charlotte</ span >
</ span ></ p >
< p >< time itemprop = "commentTime" datetime = "2013-08-29" > 5 minutes ago</ time ></ p >
</ footer >
< p > When you say "we got it down"...</ p >
</ article >
</ section >
</ article >
上記のアルゴリズムにより、次のJSON形式に変換されます(ページのURLがhttps://blog.example.com/progress-reportであると仮定します)。
{
"items" : [
{
"type" : [ "http://schema.org/BlogPosting" ],
"properties" : {
"headline" : [ "Progress report" ],
"datePublished" : [ "2013-08-29" ],
"url" : [ "https://blog.example.com/progress-report?comments=0" ],
"comment" : [
{
"type" : [ "http://schema.org/UserComments" ],
"properties" : {
"url" : [ "https://blog.example.com/progress-report#c1" ],
"creator" : [
{
"type" : [ "http://schema.org/Person" ],
"properties" : {
"name" : [ "Greg" ]
}
}
],
"commentTime" : [ "2013-08-29" ]
}
},
{
"type" : [ "http://schema.org/UserComments" ],
"properties" : {
"url" : [ "https://blog.example.com/progress-report#c2" ],
"creator" : [
{
"type" : [ "http://schema.org/Person" ],
"properties" : {
"name" : [ "Charlotte" ]
}
}
],
"commentTime" : [ "2013-08-29" ]
}
}
]
}
}
]
}
1つのエンジンでのみサポート。
全ての現在のエンジンでサポート。
すべてのには、hiddenコンテンツ属性を設定することができます。属性はであり、次のキーワードと状態があります:
| キーワード | 状態 | 簡単な説明 |
|---|---|---|
hidden |
隠されている | レンダリングされません。 |
| (空文字列) | ||
until-found |
見つかるまで隠されている | レンダリングされませんが、ページ内検索やフラグメントナビゲーションにアクセスできます。 |
この属性の欠落時のデフォルト値は、隠されていない状態であり、無効な値のデフォルトは、状態です。
要素に状態で属性が設定されている場合、それはその要素がまだ直接関連していないか、またはもはや関連していないこと、または他のページ部分で再利用されるコンテンツを宣言するために使用されていることを示します。ユーザーエージェントは、状態にある要素をレンダリングしてはいけません。この要件は、スタイルレイヤーを通じて間接的に実装される場合があります。例えば、ウェブブラウザは、レンダリングセクションで提案されているルールを使用してこれらの要件を実装できます。
要素に状態で属性が設定されている場合、それはその要素が隠されていることを示しますが、要素内のコンテンツはやにアクセスできます。これらの機能が要素のサブツリー内のターゲットにスクロールしようとする際、ユーザーエージェントはスクロールする前にコンテンツを表示するために属性を削除します。というイベントが、属性が削除される前に要素で発生します。
ウェブブラウザーは、状態の属性に対して、「display: none」の代わりに「content-visibility: hidden」を使用します。これはレンダリングセクションに指定されています。
この属性は通常CSSを使用して実装されるため、CSSを使用してオーバーライドすることも可能です。例えば、すべての要素に「display: block」を適用するルールは、状態の効果を無効にします。そのため、著者はスタイルシートを作成する際に、属性が予想通りにスタイルされていることを確認する必要があります。また、状態をサポートしないレガシーユーザーエージェントでは、「content-visibility: hidden」の代わりに「display: none」が使用されます。そのため、著者はスタイルシートが「display」または「content-visibility」プロパティを変更しないようにすることをお勧めします。
要素に状態の属性が使用されている場合、「content-visibility: hidden」の代わりに「display: none」が使用されるため、次の2つの注意点があります:
に影響を受ける必要があります。つまり、「display」値が「none」、「contents」、または「inline」の場合、要素はページ内検索で表示されません。
要素には生成されたボックスが残り、要素が隠されている状態であっても、ボーダー、マージン、およびパディングがレンダリングされます。
以下の簡単な例では、ユーザーがログインするまでウェブゲームのメイン画面を隠すために、この属性が使用されています:
< h1 > The Example Game</ h1 >
< section id = "login" >
< h2 > Login</ h2 >
< form >
...
<!-- ユーザーの資格情報が確認された後、login()を呼び出します -->
</ form >
< script >
function login() {
// 画面を切り替えます
document. getElementById( 'login' ). hidden = true ;
document. getElementById( 'game' ). hidden = false ;
}
</ script >
</ section >
< section id = "game" hidden >
...
</ section >
属性を使用して、他のプレゼンテーションで正当に表示されるコンテンツを隠してはいけません。例えば、タブ付きダイアログ内のパネルを隠すためにを使用するのは間違っています。タブ付きインターフェースはオーバーフロープレゼンテーションの一種に過ぎません。すべてのフォームコントロールをスクロールバー付きの大きなページで表示することもできます。同様に、この属性を使用してコンテンツを特定のプレゼンテーションからのみ隠すのは不適切です。とマークされたものは、すべてのプレゼンテーション(例えば、スクリーンリーダーを含む)から隠されます。
自分自身がではない要素は、である要素にを作成してはいけません。自分自身がではない要素や要素のfor属性も同様にである要素を参照してはいけません。このような参照はユーザーに混乱を引き起こします。
しかし、要素やスクリプトは、他のコンテキストでhiddenである要素を参照することができます。
例えば、属性を使用して、属性でマークされたセクションにリンクするのは誤りです。内容が適用されないか関連性がない場合、リンクする理由はありません。
しかし、ARIAの属性を使用して、である説明を参照するのは問題ありません。説明を隠すことは、それ自体が役に立たないことを意味しますが、記述される要素から参照された場合には役に立つように記述される可能性があります。
同様に、要素に属性を使用して、スクリプト化されたグラフィックスエンジンのオフスクリーンバッファとして使用することや、フォームコントロールが要素をその属性で参照することも問題ありません。
属性で隠されたセクション内の要素は依然としてアクティブであり、そのようなセクション内のスクリプトやフォームコントロールはそれぞれ実行され、送信されます。ユーザーへの表示だけが変わります。
全ての現在のエンジンでサポート。
hiddenゲッターステップは次の通りです:
属性が状態にある場合、「」を返します。
属性が設定されている場合、trueを返します。
falseを返します。
セッターステップは次の通りです:
指定された値が""に一致するASCII大文字小文字を区別しない文字列の場合、属性を""に設定します。
それ以外の場合、指定された値がfalseの場合、属性を削除します。
それ以外の場合、指定された値が空文字列である場合、属性を削除します。
それ以外の場合、指定された値がnullの場合、属性を削除します。
それ以外の場合、指定された値が0である場合、属性を削除します。
それ以外の場合、指定された値がNaNである場合、属性を削除します。
それ以外の場合、属性を空文字列に設定します。
祖先 hidden-until-found 表示アルゴリズムは、currentNodeに対して次のステップを実行します:
currentNodeが内で親ノードを持っている間:
currentNodeが状態の属性を持っている場合:
。イベントの名前はです。
currentNodeから属性を削除します。
currentNodeをcurrentNodeの親ノードに設定します。
トラバーサブルナビゲーブルのシステム可視性状態は、その作成時の初期値を含めて、ユーザーエージェントによって決定されます。これは、例えばブラウザウィンドウが最小化されているか、ブラウザタブが現在バックグラウンドにあるか、タスクスイッチャーのようなシステム要素がページを隠しているかどうかを表します。
ユーザーエージェントがシステム可視性状態がトラバーサブルナビゲーブルのtraversableに対してnewStateに変更されたと判断した場合、次のステップを実行しなければなりません。
navigablesをtraversableのアクティブドキュメントの包括的子孫ナビゲーブルに設定します。
次の順序で navigablesを繰り返します どの順序で?:
documentをnavigableのアクティブドキュメントに設定します。
documentのグローバルタスクをキューに入れ、documentの関連グローバルオブジェクトに対してnewStateで可視性状態を更新します。
Documentには可視性状態があります。それは "hidden" または "visible"
のいずれかであり、初期設定は "hidden" です。
全ての現在のエンジンでサポート。
visibilityStateゲッターステップは、thisの可視性状態を返すことです。
全ての現在のエンジンでサポート。
hiddenゲッターステップは、thisの可視性状態が"hidden"である場合はtrueを、それ以外の場合はfalseを返すことです。
Document
documentのvisibilityStateを更新するには、次の手順を実行します。
documentの可視性状態がvisibilityStateと等しい場合、戻ります。
documentの可視性状態をvisibilityStateに設定します。
新しい
VisibilityStateEntryをキューに入れ、その
可視性状態がvisibilityStateであり、
タイムスタンプが
documentの現在の高解像度時間であり、
documentの関連するグローバルオブジェクトを基にしたものです。
documentで画面の向き変更ステップを実行します。[SCREENORIENTATION]
documentでビュー遷移ページ可視性変更ステップを実行します。
他の仕様で定義されている可能性のあるページ可視性変更ステップをvisibilityStateおよびdocumentで実行します。
仕様の著者がここからの呼び出しをその仕様に直接追加するプルリクエストを送る方が、ページ可視性変更ステップフックを使用するよりも、仕様間の呼び出し順序を明確にするために望ましいです。この記事を書いている時点では、次の仕様がページ可視性変更ステップを持つことが知られており、これらは未指定の順序で実行されます: デバイス姿勢APIおよびWeb NFC。[DEVICEPOSTURE] [WEBNFC]
documentで、visibilitychangeという名前のイベントを発生させ、そのバブル属性をtrueに初期化します。
VisibilityStateEntry
インターフェイス1つのエンジンでのみサポート。
VisibilityStateEntryインターフェイスは、ドキュメントがアクティブになった瞬間から、ドキュメントへの可視性の変化を公開します。
function wasHiddenBeforeFirstContentfulPaint() {
const fcpEntry = performance. getEntriesByName( "first-contentful-paint" )[ 0 ];
const visibilityStateEntries = performance. getEntriesByType( "visibility-state" );
return visibilityStateEntries. some( e =>
e. startTime < fcpEntry. startTime &&
e. name === "hidden" );
}
ページを隠すことは、レンダリングや他のユーザーエージェント操作のスロットリングを引き起こす可能性があるため、このようなスロットリングが発生したことを示すために可視性の変化を使用することが一般的です。ただし、他の要因もブラウザによってスロットリングを引き起こす可能性があり、例えば長時間の非アクティブ期間などです。
[Exposed =(Window )]
interface VisibilityStateEntry : PerformanceEntry {
readonly attribute DOMString name ; // 継承されたnameをシャドウする
readonly attribute DOMString entryType ; // 継承されたentryTypeをシャドウする
readonly attribute DOMHighResTimeStamp startTime ; // 継承されたstartTimeをシャドウする
readonly attribute unsigned long duration ; // 継承されたdurationをシャドウする
};
VisibilityStateEntryには、関連付けられたDOMHighResTimeStamp タイムスタンプがあります。
VisibilityStateEntryには、"visible"
または "hidden" の可視性状態があります。
nameゲッターステップは、thisの可視性状態を返すことです。
entryTypeゲッターステップは、"visibility-state"を返すことです。
startTimeゲッターステップは、thisのタイムスタンプを返すことです。
durationゲッターステップは、ゼロを返すことです。
inert属性についての説明は、こちらも参照してください。
ノード(特に要素やテキストノード)は非活性にすることができます。ノードが非活性の場合:
ヒットテストは、'pointer-events'CSSプロパティが 'none' に設定されているかのように動作しなければなりません。
テキスト選択機能は、'user-select'CSSプロパティが 'none' に設定されているかのように動作しなければなりません。
ノードが編集可能である場合、そのノードは編集不可能であるかのように振る舞います。
ユーザーエージェントは、ページ内検索の目的で、そのノードを無視するべきです。
非活性ノードは通常フォーカスできず、ユーザーエージェントは非活性ノードをアクセシビリティAPIや支援技術に対して公開しません。非活性ノードがコマンドである場合、上記のようにユーザーには操作不能になります。
ただし、ユーザーエージェントは、ページ内検索やテキスト選択に関する制限をユーザーが上書きできるようにする場合があります。
デフォルトでは、ノードは非活性ではありません。
Document
documentは、subjectがdocumentのトップレイヤー内の最上位のdialog要素である場合、モーダルダイアログによってブロックされているとされます。documentがこのようにブロックされている間、subject要素とそのフラットツリーの子孫を除く、documentに接続されているすべてのノードは非活性になる必要があります。
subjectは、inert属性を使用してさらに非活性にすることもできますが、それはsubject自体に指定されている場合のみです(つまり、subjectは祖先の非活性状態を逃れます)。subjectのフラットツリーの子孫も同様の方法で非活性になることがあります。
dialog要素のshowModal()メソッドは、このメカニズムをトリガーし、dialog要素をそのノードドキュメントのトップレイヤーに追加することで、このメカニズムを引き起こします。
inert 属性すべての現在のエンジンでサポート。
inert 属性は、存在することで要素とそのフラットツリーの子孫(モーダルダイアログなど)が他の方法で非活性状態から逃れない限り、ユーザーエージェントによって非活性にされることを示すブール属性です。
非活性サブツリーには、ページの理解や使用に重要なコンテンツやコントロールを含めるべきではありません。非活性サブツリー内のコンテンツは、すべてのユーザーに認識されず、インタラクティブではありません。著者は、表示が何らかの方法で視覚的に隠されていない限り、要素を非活性として指定すべきではありません。ほとんどの場合、著者は個々のフォームコントロールにinert属性を指定すべきではありません。このような場合、disabled属性の方が適切である可能性が高いです。
次の例は、「読み込み中」メッセージによって視覚的に隠された部分的に読み込まれたコンテンツを非活性としてマークする方法を示しています。
< section aria-labelledby = s1 >
< h3 id = s1 > Population by City</ h3 >
< div class = container >
< div class = loading >< p > Loading...</ p ></ div >
< div inert >
< form >
< fieldset >
< legend > Date range</ legend >
< div >
< label for = start > Start</ label >
< input type = date id = start >
</ div >
< div >
< label for = end > End</ label >
< input type = date id = end >
</ div >
< div >
< button > Apply</ button >
</ div >
</ fieldset >
</ form >
< table >
< caption > From 20-- to 20--</ caption >
< thead >
< tr >
< th > City</ th >
< th > State</ th >
< th > 20-- Population</ th >
< th > 20-- Population</ th >
< th > Percentage change</ th >
</ tr >
</ thead >
< tbody >
<!-- ... -->
</ tbody >
</ table >
</ div >
</ div >
</ section >
「読み込み中」オーバーレイは非活性コンテンツを隠しており、その非活性コンテンツが現在アクセスできないことを視覚的に明らかにしています。見出しと「読み込み中」テキストがinert属性を持つ要素の子孫でないことに注意してください。これにより、このテキストはすべてのユーザーにアクセス可能になりますが、非活性コンテンツは誰も操作できなくなります。
デフォルトでは、要素やそのサブツリーが非活性であることを示す永続的な視覚的インディケーターはありません。このようなコンテンツに適した視覚的スタイルは、しばしばコンテキストに依存します。たとえば、オフスクリーンにある非活性ナビゲーションパネルには、デフォルトのスタイルは必要ありません。なぜなら、そのオフスクリーン位置がコンテンツを視覚的に隠すからです。同様に、モーダルdialog要素の背景は、非活性コンテンツを特にスタイリングするのではなく、ウェブページの非活性コンテンツを視覚的に隠す手段として機能します。
しかし、多くの他の状況において、著者はドキュメントのどの部分がアクティブで、どの部分が非活性であるかを明確に示すことを強く推奨します。これにより、ユーザーの混乱を避けることができます。特に、すべてのユーザーがページのすべての部分を同時に見ることができるわけではないことを忘れないでください。たとえば、スクリーンリーダーを使用しているユーザー、小さなデバイスや拡大鏡を使用しているユーザー、または特に小さなウィンドウを使用しているユーザーは、ページのアクティブな部分を見ることができず、非活性なセクションが明らかに非活性でない場合、フラストレーションを感じるかもしれません。
すべての現在のエンジンでサポート。
inert IDL 属性は、同名のコンテンツ属性を反映する必要があります。
ユーザーにとって迷惑な特定のAPI(例:ポップアップの表示や電話の振動)を乱用するのを防ぐため、ユーザーエージェントは、ユーザーがウェブページと積極的にやり取りしている場合、または少なくとも一度はページとやり取りした場合にのみ、これらのAPIを許可します。この「積極的なやり取り」状態は、このセクションで定義されたメカニズムによって維持されます。
ユーザーアクティベーションの追跡の目的で、各Window
Wには、次の2つの関連する値があります:
最後のアクティベーションタイムスタンプ、これはDOMHighResTimeStamp、正の無限大(Wが一度もアクティベートされていないことを示す)、または負の無限大(アクティベーションが消費されたことを示す)のいずれかです。初期値は正の無限大です。
最後の履歴アクションアクティベーションタイムスタンプ、これはDOMHighResTimeStampまたは正の無限大であり、初期値は正の無限大です。
ユーザーエージェントはまた、一時的なアクティベーションの期間を定義します。これは、特定のユーザーアクティベーション制御API(例:ポップアップの表示)に対してユーザーアクティベーションが有効である期間を示す定数の数値です。
一時的なアクティベーションの期間は、ユーザーがページとのやり取りとアクティベーション制御APIの呼び出しとの関連性を認識できるようにするため、数秒程度に設定されることが予想されます。
次に、Wのための以下のブール値のユーザーアクティベーション状態があります:
Wに与えられた現在の高解像度時間が、Wの最後のアクティベーションタイムスタンプ以上である場合、Wは永続的アクティベーションを持つとされます。
これはWの履歴的なアクティベーション状態であり、ユーザーがWで一度でもやり取りしたかどうかを示します。最初はfalseから始まり、Wが最初のアクティベーション通知を受け取ったときにtrueに変わり、再びfalseになることはありません。
Wに与えられた現在の高解像度時間が、Wの最後のアクティベーションタイムスタンプ以上かつWの最後のアクティベーションタイムスタンプに一時的アクティベーションの期間を加えた値未満である場合、Wは一時的アクティベーションを持つとされます。
これはWの現在のアクティベーション状態であり、ユーザーがWで最近やり取りしたかどうかを示します。最初はfalseから始まり、Wがアクティベーション通知を受け取った後、一定期間trueのままになります。
一時的アクティベーション状態は、一時的アクティベーションの期間が経過してユーザーアクティベーションが発生してからの時間が経過したためにfalseになった場合、期限切れとみなされます。また、アクティベーションの消費によって期限切れ時間の前にfalseになることもあります。
Wの最後の履歴アクションアクティベーションタイムスタンプがWの最後のアクティベーションタイムスタンプと等しくない場合、Wは履歴アクションアクティベーションを持つとされます。
これはユーザーアクティベーションの特別なバリアントであり、頻繁に使用するとブラウザーUIを使って戻るのが難しくなるセッション履歴APIへのアクセスを許可するために使用されます。最初はfalseから始まり、ユーザーがWとやり取りするたびにtrueになりますが、履歴アクションアクティベーションの消費を通じて再びfalseにリセットされます。これにより、介在するユーザーアクティベーションなしに連続して複数回このようなAPIを使用することができなくなります。ただし、一時的アクティベーションとは異なり、このようなAPIを使用するための時間制限はありません。
最後のアクティベーションタイムスタンプと最後の履歴アクションアクティベーションタイムスタンプは、Documentが完全にアクティブな状態を変更した後(例:Documentから離れた後、またはキャッシュされたDocumentに移動した後)も保持されます。これは、同じDocumentが再利用される限り、永続的アクティベーション状態が複数のナビゲーションにまたがって維持されることを意味します。一時的なアクティベーション状態については、元の有効期限時間が変更されないままです(つまり、元のアクティベーションを引き起こす入力イベントからの一時的アクティベーションの期間制限内で状態が期限切れになります)。永続的アクティベーションまたは一時的アクティベーションに基づいて特定の判断を下す際には、これを考慮することが重要です。
ユーザーの操作がDocument
document内でアクティベーションを引き起こす入力イベントの発生を引き起こした場合、ユーザーエージェントはイベントをディスパッチする前に、以下のアクティベーション通知手順を実行する必要があります:
windowsを« documentの関連するグローバルオブジェクト »に設定します。
拡張する: windowsを、documentの祖先ナビゲーブルの各アクティブウィンドウで拡張します。
拡張する: windowsを、documentの子孫ナビゲーブルの各アクティブウィンドウで拡張し、documentのオリジンと同一オリジンであるもののみを含むようにフィルタリングします。
各 windowについて:
windowの最後のアクティベーションタイムスタンプを現在の高解像度時間に設定します。
ユーザーアクティベーションについてクローズウォッチャーマネージャーに通知することを、windowを使って行います。
アクティベーションを引き起こす入力イベントとは、isTrusted属性がtrueであり、typeが以下のいずれかであるイベントを指します:
"keydown"、ただしキーがEscキーでないか、ユーザーエージェントによって予約されたショートカットキーでない場合に限ります。
"pointerdown"、ただしイベントのpointerTypeが"mouse"である場合に限ります。
"pointerup"、ただしイベントのpointerTypeが"mouse"でない場合に限ります。
"touchend"
アクティベーション消費APIは、この仕様および他の仕様で定義されており、Window
Wを与えられた場合、以下の手順を実行してユーザーアクティベーションを消費します:
もしWのナビゲーブルがnullである場合、終了します。
topをWのナビゲーブルのトップレベルのトラバーサブルに設定します。
navigablesをtopのアクティブドキュメントの包括的な子孫ナビゲーブルに設定します。
windowsを、navigables内の各項目のアクティブウィンドウを取得することによって構築されたWindowオブジェクトのリストに設定します。
各 windowについて、もしwindowの最後のアクティベーションタイムスタンプが正の無限大でない場合、windowの最後のアクティベーションタイムスタンプを負の無限大に設定します。
履歴アクションアクティベーション消費APIは、この仕様および他の仕様で定義されており、Window
Wを与えられた場合、以下の手順を実行して履歴アクションユーザーアクティベーションを消費します:
もしWのナビゲーブルがnullである場合、終了します。
topをWのナビゲーブルのトップレベルのトラバーサブルに設定します。
navigablesをtopのアクティブドキュメントの包括的な子孫ナビゲーブルに設定します。
windowsを、navigables内の各項目のアクティブウィンドウを取得することによって構築されたWindowオブジェクトのリストに設定します。
各 windowについて、windowの最後の履歴アクションアクティベーションタイムスタンプをwindowの最後のアクティベーションタイムスタンプに設定します。
アクティベーション通知とアクティベーション消費によってページ内のブラウジングコンテキストに影響を与えるセットの非対称性に注意してください。アクティベーション消費は、ページ内のすべてのブラウジングコンテキストの一時的アクティベーション状態を変更しますが(falseに)、アクティベーション通知はこれらのブラウジングコンテキストのサブセットの状態のみを変更します(trueに)。ここでの消費の包括的な性質は意図的です:これは、悪意のあるサイトが単一のユーザーアクティベーションから複数のアクティベーション消費APIを呼び出すことを防ぎます(おそらくiframeの深い階層を利用して)。
ユーザーアクティベーションに依存するAPIは、異なるレベルに分類されます:
これらのAPIは永続的アクティベーション状態がtrueであることを必要とするため、最初のユーザーアクティベーションまでブロックされます。
これらのAPIは一時的アクティベーション状態がtrueであることを必要としますが、それを消費しないため、一時的状態が期限切れになるまで、1つのユーザーアクティベーションにつき複数回の呼び出しが許可されます。
これらのAPIは一時的アクティベーション状態がtrueであることを必要とし、各呼び出しでユーザーアクティベーションを消費することで、1つのユーザーアクティベーションにつき複数回の呼び出しを防ぎます。
これらのAPIは履歴アクションアクティベーション状態がtrueであることを必要とし、各呼び出しで履歴アクションユーザーアクティベーションを消費することで、1つのユーザーアクティベーションにつき複数回の呼び出しを防ぎます。
UserActivation インターフェース各Windowには、関連付けられたUserActivationがあり、これはUserActivationオブジェクトです。Windowオブジェクトが作成されると、その関連付けられたUserActivationは、そのWindowオブジェクトの関連するレルムで作成された新しいUserActivationオブジェクトに設定されます。
[Exposed =Window ]
interface UserActivation {
readonly attribute boolean hasBeenActive ;
readonly attribute boolean isActive ;
};
partial interface Navigator {
[SameObject ] readonly attribute UserActivation userActivation ;
};
navigator.userActivation.hasBeenActive
ウィンドウが永続的アクティベーションを持っているかどうかを返します。
navigator.userActivation.isActive
ウィンドウが一時的アクティベーションを持っているかどうかを返します。
userActivationのgetterステップは、thisの関連するグローバルオブジェクトの関連付けられたUserActivationを返すことです。
hasBeenActiveのgetterステップは、thisの関連するグローバルオブジェクトが永続的アクティベーションを持っている場合にtrueを返し、それ以外の場合はfalseを返すことです。
isActiveのgetterステップは、thisの関連するグローバルオブジェクトが一時的アクティベーションを持っている場合にtrueを返し、それ以外の場合はfalseを返すことです。
ユーザーエージェントの自動化およびアプリケーションテストの目的で、この仕様はWebDriver仕様のために以下の拡張コマンドを定義します。以下の拡張コマンドをサポートするかどうかは、ユーザーエージェントの任意です。[WEBDRIVER]
| HTTP メソッド | URI テンプレート |
|---|---|
POST |
/session/{session id}/window/consume-user-activation |
リモートエンドステップは以下の通りです:
現在のブラウジングコンテキストのアクティブウィンドウをwindowとします。
windowが一時的アクティベーションを持っている場合は、consumeをtrueとし、それ以外の場合はfalseとします。
もしconsumeがtrueであれば、windowのユーザーアクティベーションを消費します。
データconsumeと共に成功を返します。
HTMLの特定の要素にはアクティベーション動作があり、ユーザーがそれらをアクティベートすることができます。これは常にclickイベントによって引き起こされます。
ユーザーエージェントは、アクティベーション動作を持つ要素を、キーボードや音声入力、マウスクリックなどを使用して手動でトリガーできるようにすべきです。ユーザーがクリック以外の方法で定義されたアクティベーション動作を持つ要素をトリガーした場合、そのインタラクションイベントのデフォルトアクションは、その要素でclickイベントを発火させることになります。
element.click()
すべての現在のエンジンでサポートされています。
要素がクリックされたかのように動作します。
各要素には、進行中のクリックフラグが関連付けられており、これは最初は未設定です。
click()メソッドは、次の手順を実行しなければなりません:
この要素が無効化されたフォームコントロールである場合、終了します。
この要素の進行中のクリックフラグが設定されている場合、終了します。
この要素の進行中のクリックフラグを設定します。
合成ポインターイベントを発火させ、clickという名前のイベントを、この要素に対してnot
trusted flagを設定して発火させます。
この要素の進行中のクリックフラグを解除します。
ToggleEvent インターフェイスすべての現在のエンジンでサポートされています。
すべての現在のエンジンでサポートされています。
[Exposed =Window ]
interface ToggleEvent : Event {
constructor (DOMString type , optional ToggleEventInit eventInitDict = {});
readonly attribute DOMString oldState ;
readonly attribute DOMString newState ;
};
dictionary ToggleEventInit : EventInit {
DOMString oldState = "";
DOMString newState = "";
};
event.oldState
閉から開へ遷移する場合は "closed" に設定され、開から閉へ遷移する場合は "open" に設定されます。
event.newState
閉から開へ遷移する場合は "open" に設定され、開から閉へ遷移する場合は "closed" に設定されます。
すべての現在のエンジンでサポートされています。
すべての現在のエンジンでサポートされています。
oldStateおよびnewState属性は、初期化された値を返さなければなりません。
トグルタスクトラッカーは、構造体で、次のものを持ちます:
ToggleEventを発火するタスク。
oldState属性の値を表す文字列。
このセクションは規範的ではありません。
HTML ユーザーインターフェースは通常、フォームコントロール、スクロール可能な領域、リンク、ダイアログボックス、ブラウザタブなどの複数のインタラクティブなウィジェットで構成されます。これらのウィジェットは階層を形成しており、(例えばブラウザタブやダイアログボックスのように)他のウィジェット(リンクやフォームコントロールなど)を含んでいるものもあります。
キーボードを使用してインターフェースと対話する場合、キー入力はシステムからインタラクティブなウィジェットの階層を通じてアクティブなウィジェットにチャネリングされ、これがフォーカスされていると言われます。
グラフィカルな環境で動作するブラウザタブ内で実行されている HTML アプリケーションを考えてみましょう。このアプリケーションが、いくつかのテキストコントロールやリンクを持ち、モーダルダイアログを表示しており、そのダイアログ内にはテキストコントロールとボタンがあるとします。
このシナリオにおけるフォーカス可能なウィジェットの階層には、ブラウザウィンドウが含まれ、その子として HTML アプリケーションを含むブラウザタブがあります。タブ自体は、さまざまなリンクやテキストコントロール、ダイアログなどの子を持ちます。ダイアログ自体は、テキストコントロールとボタンを子として持ちます。
この例でフォーカスされているウィジェットがダイアログボックス内のテキストコントロールである場合、キー入力はグラフィカルシステムから①ウェブブラウザ、次に②タブ、次に③ダイアログ、そして最後に④テキストコントロールにチャネリングされます。
キーボードイベントは常にこのフォーカスされた要素をターゲットにします。
トップレベルのトラバーサブルは、オペレーティングシステムからチャネルされるキーボード入力を受け取ることができる場合、その システムフォーカス を持ちます。これは、アクティブなドキュメント の 子孫ナビゲーブル のいずれかをターゲットにしている可能性があります。
トップレベルのトラバーサブルは、ユーザーの注目を持つとき、そのシステムの可視性状態が「visible」であり、かつ システムフォーカス
を持つか、それに直接関連するユーザーエージェントのウィジェットがオペレーティングシステムからチャネルされるキーボード入力を受け取ることができる場合です。
ブラウザウィンドウがフォーカスを失うとユーザーの注目も失われますが、システムフォーカスはブラウザウィンドウ内の他のシステムウィジェット(例:ロケーションバー)に移ることもあります。
Document d は、d が 完全にアクティブであり、d の ノードナビゲーブル の トップレベルのトラバーサブル がユーザーの注目を持つ場合、ユーザーの注目を持つトップレベルのトラバーサブルの完全にアクティブな子孫です。
フォーカス可能エリアという用語は、そのようなキーボード入力のターゲットになる可能性があるインターフェイスの領域を指すために使用されます。フォーカス可能エリアは、要素、要素の一部、またはユーザーエージェントによって管理される他の領域である可能性があります。
各フォーカス可能エリアにはDOMアンカーがあり、これは
Node
オブジェクトで、DOM内のフォーカス可能エリアの位置を表します。(フォーカス可能エリアがそれ自体がNodeである場合、それ自体がDOMアンカーです。)DOMアンカーは、フォーカス可能エリアを表す他のDOMオブジェクトがない場合に、いくつかのAPIでその代わりに使用されます。
次の表は、フォーカス可能エリアになり得るオブジェクトについて説明しています。左側の列は フォーカス可能エリア になり得るオブジェクトを説明し、右側の列はそれらの要素の DOMアンカー を説明しています。(両方の列にまたがるセルは、規範的でない例です。)
| フォーカス可能エリア | DOMアンカー |
|---|---|
| 例 | |
次のすべての条件を満たす要素:
| 要素自体。 |
|
| |
エリア 要素の形状が、イメージマップ内で関連付けられた
img 要素と共に レンダリングされている かつ 無効化されていない 場合の形状。
|
img要素。
|
|
次の例では、
| |
| レンダリングされている、かつ実際に無効化されていないまたはイナートではない要素のユーザーエージェント提供のサブウィジェット。 | フォーカス可能エリアがサブウィジェットである要素。 |
|
ユーザーインターフェースのコントロールが | |
| レンダリングされている、かつイナートではない要素のスクロール可能な領域。 | スクロール可能な領域がスクロールするボックスが作成された要素。 |
|
CSS の 'overflow' プロパティの 'scroll' 値は、通常、スクロール可能な領域を作成します。 | |
Document の ブラウジングコンテキスト が null ではなく、イナートではない場合の ビューポート。
|
ビューポートが作成された Document。
|
|
| |
| 特にアクセシビリティの向上やプラットフォームの慣習により良く一致させるために、ユーザーエージェントがフォーカス可能エリアと判断したその他の要素または要素の一部。 | 要素。 |
|
ユーザーエージェントは、ユーザーがリストをより簡単にナビゲートできるように、すべてのリスト項目の箇条書きを順次フォーカス可能にすることができます。 同様に、ユーザーエージェントは、 | |
ナビゲーブルコンテナ(例:iframe)はフォーカス可能エリアですが、ナビゲーブルコンテナにルーティングされるキーイベントは、直ちにそのコンテンツナビゲーブルのアクティブドキュメントにルーティングされます。同様に、順次フォーカスナビゲーションでは、ナビゲーブルコンテナは基本的にそのコンテンツナビゲーブルのアクティブドキュメントのためのプレースホルダーとして機能します。
各 フォーカス可能エリア は Document の ドキュメントのフォーカスされたエリアに指定されます。このコントロールがいつそう指定されるかは、この仕様のアルゴリズムに基づいて時間と共に変化します。
ドキュメントが 完全にアクティブ ではなく、ユーザーに表示されていない場合でも、ドキュメントのフォーカスされたエリアを持つことができます。ドキュメントの完全にアクティブな状態が変わっても、そのフォーカスされたエリアは同じままです。
現在フォーカスされているトップレベルのトラバーサブルのフォーカスエリア traversable は、次のアルゴリズムによって返される フォーカス可能エリアまたはnullです:
traversable が システムフォーカス を持っていない場合、null を返します。
candidate を traversable の アクティブドキュメント に設定します。
candidate の フォーカスされたエリアが非nullであり、かつ ナビゲーブルコンテナ であり、コンテンツナビゲーブル が非nullである場合は、その アクティブドキュメント をcandidateに設定します。
もし candidate の フォーカスされたエリア が非nullである場合、candidate をそのフォーカスされたエリアに設定します。
candidate を返します。
トップレベルのトラバーサブルの現在のフォーカスチェーン traversable は、非nullの場合は 現在フォーカスされているトップレベルのトラバーサブルのフォーカスエリアのフォーカスチェーン、そうでない場合は空のリストです。
ある要素が DOM アンカー として フォーカス可能な領域 に関連付けられている場合、その フォーカス可能な領域 が トップレベルのトラバーサブルの現在フォーカスされている領域 になるときに、その要素は フォーカスを得る と言います。ある要素が DOM アンカー として フォーカス可能な領域 に関連付けられている場合、その要素が トップレベルのトラバーサブルの現在フォーカスされている領域 であるとき、その要素は フォーカスされている と言います。
フォーカスチェーンは、フォーカス可能エリア subject に対して次のように構築された順序リストです:
outputを空のリストとします。
currentObjectをsubjectとします。
次のループを実行します:
Append currentObjectをoutputに追加します。
currentObjectがarea要素の形状である場合、そのarea要素をoutputに追加します。
それ以外の場合、currentObjectのDOMアンカーがcurrentObject自体でない要素である場合、そのcurrentObjectのDOMアンカーをoutputに追加します。
currentObjectがフォーカス可能エリアである場合、currentObjectをそのDOMアンカーのノードドキュメントに設定します。
それ以外の場合、currentObjectがDocumentであり、かつそのノードナビゲーブルの親が非nullである場合、currentObjectをそのノードナビゲーブルの親に設定します。
それ以外の場合、breakします。
outputを返します。
このチェーンはsubjectから始まり(subjectが現在フォーカスされているトップレベルのトラバーサブルのフォーカスエリアであるか、その可能性がある場合)、フォーカス階層の最上部にあるトップレベルのトラバーサブルのDocumentまで続きます。
すべてのフォーカス可能エリアは、フォーカス可能であるとされています。
フォーカス可能エリアには、次の2つの特別なフォーカス性のタイプがあります:
フォーカス可能エリアは、そのDocument の順次フォーカスナビゲーションの順序
に含まれており、かつユーザーエージェントが順次フォーカス可能と判断した場合、順次フォーカス可能であるとされます。
フォーカス可能エリアは、ユーザーエージェントがクリックフォーカス可能と判断した場合、クリックフォーカス可能であるとされます。ユーザーエージェントは、tabindex 値が非nullのフォーカス可能エリアをクリックフォーカス可能と考慮すべきです。
フォーカス可能でない要素はフォーカス可能エリアではなく、したがって順次フォーカス可能でもクリックフォーカス可能でもありません。
フォーカス可能であるというのは、要素がfocus()メソッドやautofocus属性を介してプログラム的にフォーカスされる可能性があるかどうかについての声明です。それに対して、順次フォーカス可能およびクリックフォーカス可能は、それぞれ順次フォーカスナビゲーションやアクティベーション動作に対するユーザーエージェントの応答方法に関連しています。
ユーザーエージェントは、要素がフォーカス可能であり、そのDocumentの順次フォーカスナビゲーションの順序に含まれていても、ユーザーの設定に応じて、順次フォーカス可能ではないと判断する場合があります。例えば、macOSのユーザーは、ユーザーエージェントに、順次フォーカスナビゲーションで非フォームコントロール要素をスキップするように設定できます。また、Tabキーだけを使った場合(OptionキーとTabキーを同時に使わない場合)には、リンクをスキップすることもできます。
同様に、ユーザーエージェントは、要素がクリックフォーカス可能であると判断しない場合もあります。例えば、いくつかのユーザーエージェントでは、編集不可能なフォームコントロールをクリックしても、それがフォーカスされない、つまり、そのようなコントロールはクリックフォーカス可能ではないと判断されます。
したがって、要素はフォーカス可能であっても、順次フォーカス可能でもクリックフォーカス可能でもない場合があります。例えば、いくつかのユーザーエージェントでは、負の整数のtabindex 値を持つ編集不可能なフォームコントロールは、ユーザー操作ではなく、プログラム的なAPIを介してのみフォーカス可能です。
ユーザーがアクティベーションをクリックフォーカス可能なフォーカス可能エリアに対して行ったとき、ユーザーエージェントはフォーカス処理手順をフォーカス可能エリアに対して実行し、フォーカストリガーを「click」に設定します。
フォーカスすることは、アクティベーション動作ではありません。つまり、要素に対してclick()メソッドを呼び出したり、合成clickイベントをディスパッチしたりしても、要素がフォーカスされることはありません。
ノードは、フォーカスナビゲーションスコープの所有者です。これは、ドキュメント、シャドウホスト、スロット、または ポップオーバー表示状態 にあり、さらに ポップオーバーインボーカー が設定されている要素です。
各 フォーカスナビゲーションスコープの所有者 には フォーカスナビゲーションスコープ があり、これは要素のリストです。その内容は次のように決定されます:
すべての要素 element には 関連フォーカスナビゲーション所有者 があり、それは null または フォーカスナビゲーションスコープの所有者 です。次のアルゴリズムで決定されます:
element の親が null である場合、null を返します。
element の親が シャドウホスト である場合、element の 割り当てられたスロット を返します。
element が ポップオーバー表示状態 にあり、ポップオーバーインボーカー が設定されている場合、element を返します。
element の親の 関連フォーカスナビゲーション所有者 を返します。
次に、特定の フォーカスナビゲーションスコープの所有者 owner の フォーカスナビゲーションスコープ の内容は、関連フォーカスナビゲーション所有者 が owner であるすべての要素です。
フォーカスナビゲーションスコープ 内の要素の順序は、この仕様のアルゴリズムには影響しません。順序は、次に定義される tabindex-順序フォーカスナビゲーションスコープ と 平坦化された tabindex-順序フォーカスナビゲーションスコープ の概念においてのみ重要になります。
tabindex-順序フォーカスナビゲーションスコープ は、フォーカス可能エリア と フォーカスナビゲーションスコープの所有者 のリストです。すべての フォーカスナビゲーションスコープの所有者 owner は tabindex-順序フォーカスナビゲーションスコープ を持っており、その内容は次のように決定されます:
owner の フォーカスナビゲーションスコープ 内のすべての要素が含まれます。それらは自らが フォーカスナビゲーションスコープの所有者 であるものです。ただし、その要素の tabindex 値 が負の整数であるものを除きます。
owner の フォーカスナビゲーションスコープ 内の要素の DOM アンカー が フォーカス可能エリア に含まれます。ただし、その tabindex 値 が負の整数であるものを除きます。
tabindex-順序フォーカスナビゲーションスコープ 内の順序は、各要素の tabindex 値 によって決定されます。以下のセクションで説明されています。
ここでのルールは厳密な順序を示しているわけではなく、「すべき」文と相対的な順序が主に構成されています。
平坦化された tabindex-順序フォーカスナビゲーションスコープ は、フォーカス可能エリア のリストです。すべての フォーカスナビゲーションスコープの所有者 owner は、独自の 平坦化された tabindex-順序フォーカスナビゲーションスコープ を所有しており、その内容は次のアルゴリズムで決定されます:
owner の クローン を result とします。これは owner の tabindex-順序フォーカスナビゲーションスコープ のクローンです。
result の各 item について:
item が フォーカスナビゲーションスコープの所有者 でない場合、続行 します。
item が フォーカス可能エリア でない場合、item を item の 平坦化された tabindex-順序フォーカスナビゲーションスコープ のすべての項目に置き換えます。
それ以外の場合、item の 平坦化された tabindex-順序フォーカスナビゲーションスコープ の内容を item の後に挿入します。
tabindex 属性すべての現在のエンジンでサポートされています。
tabindex
コンテンツ属性は、要素と、その要素を DOM アンカー として持つ領域を フォーカス可能エリア にし、それらが 順次フォーカス可能
かどうかを決定し、順次フォーカスナビゲーションの相対的な順序を決定するために使用されます。
"tab index" という名前は、フォーカス可能な要素を移動するために Tab キーを使用する一般的な使用法に由来しています。"tabbing" という用語は、順次フォーカス可能 な フォーカス可能エリア を進んでいくことを指します。
指定されている場合、tabindex 属性は、有効な整数 である必要があります。正の数値は、要素の フォーカス可能エリア の 順次フォーカスナビゲーションの順序
における相対的な位置を示し、負の数値は、そのコントロールが 順次フォーカス可能 ではないことを示します。
開発者は、自分の tabindex 属性に 0 や −1
以外の値を使用する際には注意が必要です。これは正しく行うのが複雑です。
次の内容は、tabindex
属性値の可能な動作の非規範的な概要を示しています。下記の処理モデルでは、より正確なルールが示されています。
tabindex
属性値が大きい要素が後に来るようにします。
注意:tabindex
属性を使用して要素を非フォーカス可能にすることはできません。ページの作成者がそれを行う唯一の方法は、要素を 無効 にするか、非活性 にすることです。
要素の tabindex 値 は、その tabindex 属性の値です。整数を解析するためのルール
を使用して解析されます。解析に失敗するか、属性が指定されていない場合、tabindex
値 は null になります。
tabindex 値は、フォーカス可能な領域のtabindex 値であり、そのDOM アンカーの tabindex 値を示します。
要素の tabindex 値 は次のように解釈されなければなりません:
ユーザーエージェントは、プラットフォームの慣習に従って、要素が フォーカス可能エリア と見なされるべきかどうかを判断し、そうであれば、その要素と、その要素を DOM アンカー として持つ フォーカス可能エリア が 順次フォーカス可能 であるかどうかを判断し、そうであれば、tabindex-順序フォーカスナビゲーションスコープ 内での相対的な位置を決定します。要素が フォーカスナビゲーションスコープの所有者 である場合、それが フォーカス可能エリア でない場合でも、tabindex-順序フォーカスナビゲーションスコープ に含めなければなりません。
プラットフォームの慣習を除き、次の要素は フォーカス可能エリア と見なされ、順次フォーカス可能 と見なされるべきであることが推奨されます:
ユーザーエージェントは要素を フォーカス可能エリア と見なさなければなりませんが、tabindex-順序フォーカスナビゲーションスコープ からは要素を省略するべきです。
順次フォーカスナビゲーションが著者に要素への移動を許可する必要がないという要件を無視する正当な理由の一つは、ユーザーがフォーカスを移動する唯一の手段が順次フォーカスナビゲーションである場合です。例えば、キーボードのみを使用するユーザーは、負の
tabindex
を持つテキストコントロールをクリックできないため、そのユーザーのユーザーエージェントは、そのコントロールに移動することを許可するのが妥当でしょう。
ユーザーエージェントは要素を フォーカス可能エリア と見なし、その要素を DOM アンカー とする フォーカス可能エリア を 順次フォーカス可能 と見なすべきです。
同じ フォーカスナビゲーションスコープ に属し、その tabindex 値 が 0 の要素および フォーカス可能エリア の tabindex-順序フォーカスナビゲーションスコープ 内での相対的な順序は、シャドウインクルーディングツリー順序 に従うべきです。
ユーザーエージェントは要素を フォーカス可能エリア と見なし、その要素を DOM アンカー とする フォーカス可能エリア を 順次フォーカス可能 と見なし、要素を含む tabindex-順序フォーカスナビゲーションスコープ 内に配置する必要があります。同じ フォーカスナビゲーションスコープ に属する他の要素および フォーカス可能エリア に対して、それらが次のようになるように配置されます:
tabindex
属性が省略されているか、解析時にエラーを返す場合の前、
tabindex 属性の値が 0
以下の場合の前、
tabindex 属性の値が 0
より大きく、candidate の
tabindex
属性の値より小さい場合の後、
tabindex 属性の値が
candidate の
tabindex
属性の値と等しいが、candidate より
シャドウを含むツリー順序で前に位置する場合の後、
tabindex 属性の値が
candidate の
tabindex
属性の値と等しいが、candidate より
シャドウを含むツリー順序で後に位置する場合の前、および
tabindex 属性の値が
candidate の
tabindex
属性の値より大きい場合の前。
すべての現在のエンジンでサポートされています。
tabIndex
IDL
属性は 反映 される必要があり、tabindex コンテンツ属性の値を反映します。デフォルト値 は、要素が a、area、button、frame、iframe、input、object、select、textarea、または SVG a 要素である場合、または その親の詳細に関する概要 である要素 summary です。デフォルト値 は、それ以外の場合は −1 です。
要素タイプに基づく異なるデフォルト値は、歴史的な遺物です。
focus targetが、フォーカス可能エリアでない要素、またはナビゲイブルである場合に、オプションの文字列focus
trigger(デフォルトは「other」)が与えられたときにフォーカス可能エリアを取得するには、次のリストから最初に一致する手順を実行します。
area要素で、それらがフォーカス可能エリアである場合
その要素の最初のスクロール可能領域を返します。フラットツリーの先行順で、深さ優先でツリーを走査します。[CSSSCOPING]
ナビゲイブルコンテナのコンテンツナビゲイブルのアクティブ文書を返します。
focusedElementを、トップレベルのトラバーサブルのDOMアンカーの現在フォーカスされているエリアとします。
focus targetがfocusedElementのシャドウ含む包括的な祖先である場合は、focusedElementを返します。
focus targetのfocus triggerに対してフォーカスデリゲートを返します。
順次フォーカス可能性については、シャドウホストとフォーカス委譲の処理は、順次フォーカスナビゲーション順序の構築時に行われます。つまり、順次フォーカスナビゲーションの一部としてフォーカス手順がこのようなシャドウホストに対して呼び出されることはありません。
nullを返します。
focusTargetのフォーカスデリゲートは、オプションの文字列focusTrigger(デフォルトは「other」)が与えられた場合に、以下の手順によって決定されます。
focusTargetがシャドウホストであり、そのシャドウルートのフォーカス委譲がfalseである場合は、nullを返します。
whereToLookをfocusTargetに設定します。
autofocusDelegateを、whereToLookのfocusTriggerに対するオートフォーカスデリゲートとして設定します。
autofocusDelegateがnullでない場合、autofocusDelegateを返します。
各descendantに対して、whereToLookの子孫のツリー順で以下の処理を行います。
focusableAreaをnullに設定します。
focusTargetがdialog要素であり、descendantが順次フォーカス可能である場合、focusableAreaをdescendantに設定します。
それ以外の場合、focusTargetがdialogでない場合で、descendantがフォーカス可能エリアである場合、focusableAreaをdescendantに設定します。
それ以外の場合、focusableAreaをdescendantのフォーカス可能エリアを取得する結果に設定し、focusTriggerを与えます。
このステップは再帰的になる可能性があり、フォーカス可能エリアを取得する手順は、descendantのフォーカスデリゲートを返すことがあります。
focusableAreaがnullでない場合、focusableAreaを返します。
ここではシャドウ含む子孫を見ていないことが重要です。代わりに、子孫だけを見ています。シャドウホストは、上記の再帰的なケースで処理されます。
nullを返します。
上記のアルゴリズムは、フォーカス可能エリアの最初の適切なものを返し、そのDOMアンカーとfocusTargetの間のパスが、シャドウツリー境界でフォーカスを委譲します。
focus targetのオートフォーカスデリゲートは、focus triggerが与えられた場合に、以下の手順によって決定されます。
各子孫に対して、focus targetのツリー順で以下の処理を行います。
descendantがautofocus属性を持っていない場合、続行します。
focusable areaを、descendantがフォーカス可能エリアである場合にはdescendantに、そうでない場合には、descendantのフォーカス可能エリアを取得する結果に設定し、focus triggerを与えます。
focusable areaがnullの場合は、続行します。
focusable areaがクリックフォーカス可能でなく、focus
triggerが「click」の場合は、続行します。
focusable areaを返します。
nullを返します。
new focus targetがフォーカス可能エリア、フォーカス可能エリアでない要素、またはナビゲイブルのいずれかである場合、次の手順を実行します。これらはオプションでfallback targetおよび文字列focus triggerとともに実行できます。
new focus targetがフォーカス可能エリアでない場合、new focus targetをfocus triggerが与えられている場合には、new focus targetのフォーカス可能エリアを取得する結果に設定します。
new focus targetがnullの場合は:
fallback targetが指定されていない場合は、終了します。
それ以外の場合は、new focus targetをfallback targetに設定します。
new focus targetが非nullのコンテンツナビゲイブルを持つナビゲイブルコンテナである場合、new focus targetをコンテンツナビゲイブルのアクティブ文書に設定します。
new focus targetがフォーカス可能エリアであり、そのDOMアンカーがインアートである場合、終了します。
new focus targetがトップレベルのトラバーサブルの現在のフォーカス領域である場合、終了します。
old chainを、new focus targetが見つかるトップレベルのトラバーサブルの現在のフォーカスチェーンとします。
new chainを、new focus targetのフォーカスチェーンとします。
old chain、new chain、およびnew focus targetをそれぞれ使用してフォーカス更新手順を実行します。
ユーザーエージェントは、candidateにフォーカスを移動しようとするときに、candidateのフォーカス可能エリアまたはナビゲイブルに対してフォーカス手順を即座に実行しなければなりません。
old focus targetがフォーカス可能エリアまたはフォーカス可能エリアでない要素のいずれかである場合、次の手順を実行します。
old focus target が、その シャドウホスト の シャドウルート の フォーカス委譲 が true の場合、 かつ old focus target の シャドウルート が シャドウを含む包括的な祖先 であり、トップレベルのトラバーサブルの現在フォーカスされている領域 の DOM アンカー である場合、 old focus target を トップレベルのトラバーサブルの現在フォーカスされている領域 に設定します。
old focus targetがインアートである場合、終了します。
old focus targetがarea要素であり、その形状の1つが現在フォーカスされているエリアである場合、または、old
focus targetが1つ以上のスクロール可能領域を持つ要素であり、そのうちの1つが現在フォーカスされているエリアである場合、old
focus targetをその現在フォーカスされているエリアに設定します。
old chainを、old focus targetが見つかる現在のフォーカスチェーンとします。
old focus targetがold chainのエントリの1つでない場合、終了します。
old focus targetがフォーカス可能エリアでない場合、終了します。
topDocumentをold chainの最後のエントリとします。
topDocumentのノードナビゲイブルがシステムフォーカスを持っている場合、topDocumentのビューポートに対してフォーカス手順を実行します。
それ以外の場合、topDocumentのノードナビゲイブルからシステムフォーカスを取り除くための関連するプラットフォーム固有の規約を適用し、old chain、空のリスト、およびnullを与えてフォーカス更新手順を実行します。
アンフォーカス手順は、トップレベルのトラバーサブルの現在フォーカスされているエリアに適用された場合でも、必ずしもフォーカスが変わるわけではありません。例えば、トップレベルのトラバーサブルの現在フォーカスされているエリアがビューポートである場合、通常は他のフォーカス可能エリアがフォーカス手順で明示的にフォーカスされるまで、そのままフォーカスを保持します。
フォーカス更新手順は、old chain、new chain、およびnew focus targetが与えられた場合に、次のように実行されます:
old chainの最後のエントリとnew chainの最後のエントリが同じ場合は、old chainとnew chainから最後のエントリをポップして、このステップをやり直します。
old chainの各エントリentryに対して、順番に次のサブステップを実行します:
entryがinput要素であり、changeイベントがその要素に適用され、要素が定義されたアクティベーション動作を持たず、ユーザーがそのコントロールにフォーカスが当たっている間に要素の値または選択されたファイルのリストを変更したが、その変更をコミットせず(つまり、コントロールが最初にフォーカスされたときと異なる状態である場合)、次のようにします:
entryが要素である場合、blur event targetをentryとします。
entryがDocumentオブジェクトである場合、blur
event targetをそのDocumentオブジェクトの関連グローバルオブジェクトとします。
それ以外の場合、blur event targetをnullにします。
entryがold chainの最後のエントリであり、かつentryがElementであり、new
chainの最後のエントリもElementである場合、related
blur targetをnew chainの最後のエントリとします。それ以外の場合、related blur
targetをnullにします。
blur event targetがnullでない場合、related blur targetを関連ターゲットとして、blurという名前のフォーカスイベントを発生させます。
場合によっては、entryがarea要素の形状、スクロール可能な領域、またはビューポートである場合、イベントが発生しないことがあります。
new focus targetにフォーカスを合わせるために、関連するプラットフォーム固有の規約を適用します。(例えば、いくつかのプラットフォームでは、テキストコントロールにフォーカスが当たると、そのコントロールの内容が選択されます。)
new chainの各エントリentryに対して、逆順で次のサブステップを実行します:
entryがフォーカス可能エリアであり、文書のフォーカス領域がentryでない場合:
documentの関連グローバルオブジェクトのナビゲーションAPIの進行中のナビゲーション中にフォーカスが変更されたをtrueに設定します。
entryを文書のフォーカス領域として指定します。
entryが要素である場合、focus event targetをentryとします。
entryがDocumentオブジェクトである場合、focus
event targetをそのDocumentオブジェクトの関連グローバルオブジェクトとします。
それ以外の場合、focus event targetをnullにします。
entryがnew chainの最後のエントリであり、かつentryがElementであり、old
chainの最後のエントリもElementである場合、related
focus targetをold chainの最後のエントリとします。それ以外の場合、related focus
targetをnullにします。
focus event targetがnullでない場合、related focus targetを関連ターゲットとして、focusという名前のフォーカスイベントを発生させます。
場合によっては、entryがarea要素の形状、スクロール可能な領域、またはビューポートである場合、イベントが発生しないことがあります。
フォーカスイベントを発生させるには、eという名前のイベントを、関連ターゲットrを指定して、要素tに発生させます。イベントを発生させ、FocusEventを使用し、relatedTarget属性をrに初期化し、view属性をtのノード文書の関連グローバルオブジェクトに初期化し、合成フラグを設定します。
キーイベントがトップレベルのトラバーサブルでルーティングされるとき、ユーザーエージェントは次の手順を実行しなければなりません:
target areaをトップレベルのトラバーサブルの現在フォーカスされているエリアとします。
アサート: target areaはnullではありません。キーイベントは、システムフォーカスを持つトップレベルのトラバーサブルにのみルーティングされるため、target areaはフォーカス可能エリアです。
target nodeをtarget areaのDOMアンカーとします。
target nodeがDocumentであり、本文要素を持っている場合、target nodeをそのDocumentの本文要素とします。
それ以外の場合、target nodeがDocumentオブジェクトであり、非nullの文書要素を持っている場合、target nodeをその文書要素とします。
target nodeがインアートでない場合は、次のようにします:
フォーカスがあるかどうかの手順は、targetとしてDocumentオブジェクトが与えられた場合に、次のように実行されます:
targetのナビゲイブルノードのトップレベルのトラバーサブルがシステムフォーカスを持っていない場合、falseを返します。
candidateをtargetのナビゲイブルノードのトップレベルのトラバーサブルのアクティブ文書とします。
次の手順を繰り返します:
candidateがtargetである場合、trueを返します。
candidateの文書のフォーカス領域が非nullのコンテンツナビゲイブルを持つナビゲイブルコンテナである場合、candidateをそのナビゲイブルコンテナのコンテンツナビゲイブルのアクティブ文書に設定します。
それ以外の場合、falseを返します。
各Documentには、いくつかまたはすべてのフォーカス可能エリアを互いに関連付けて並べ替える順次フォーカスナビゲーション順序があります。その内容と順序は、Documentのフラットなタブインデックス順のフォーカスナビゲーションスコープによって決定されます。
フラットなタブインデックス順のフォーカスナビゲーションスコープを定義するルールにより、この順序はDocumentのツリー順と必ずしも関連しているわけではありません。
フォーカス可能エリアがそのDocumentの順次フォーカスナビゲーション順序から除外されている場合、そのエリアは順次フォーカスナビゲーションを使用して到達することはできません。
順次フォーカスナビゲーションの開始点が存在する場合もあります。それは初めは設定されていません。ユーザーエージェントは、ユーザーが移動を指示したときにそれを設定することがあります。
たとえば、ユーザーが文書内容をクリックした場合、ユーザーエージェントはその位置に設定することがあります。
ユーザーエージェントは、フラグメントへのナビゲーション時に順次フォーカスナビゲーションの開始点をターゲット要素に設定する必要があります。
ユーザーがトップレベルのトラバーサブルの現在フォーカスされているエリアから次または前のフォーカス可能エリアへフォーカスを移動するようにリクエストした場合(たとえば、tabキーを押すことによるデフォルトの動作として)、またはユーザーが最初にトップレベルのトラバーサブルに順次フォーカスを移動するようにリクエストした場合(たとえば、ブラウザのロケーションバーから)、ユーザーエージェントは次のアルゴリズムを使用しなければなりません:
starting pointを、ユーザーがそこから順次フォーカスを移動するようリクエストした場合はトップレベルのトラバーサブルの現在フォーカスされているエリアとし、そうでない場合はユーザーがその外部からフォーカスを移動するようにリクエストしたトップレベルのトラバーサブル自体とします。
定義されている順次フォーカスナビゲーションの開始点があり、それがstarting pointの内部にある場合、starting pointを順次フォーカスナビゲーションの開始点に変更します。
ユーザーが次のコントロールを要求した場合はdirectionを前方、前のコントロールを要求した場合はdirectionを後方とします。
通常、tabキーを押すと次のコントロールが要求され、shift + tabキーを押すと前のコントロールが要求されます。
ループ: starting pointがナビゲイブルである場合、またはstarting pointがそのDocumentの順次フォーカスナビゲーション順序に含まれている場合、selection
mechanismを順次とします。
それ以外の場合、starting pointはそのDocumentの順次フォーカスナビゲーション順序に含まれていないため、selection
mechanismをDOMとします。
candidateを、starting point、direction、およびselection mechanismを引数として順次ナビゲーション検索アルゴリズムを実行した結果とします。
candidateがnullでない場合、candidateに対してフォーカス手順を実行し、終了します。
それ以外の場合、順次フォーカスナビゲーションの開始点を解除します。
starting pointがトップレベルのトラバーサブルまたはそのフォーカス可能エリアである場合、ユーザーエージェントはdirectionに従って適切にそのコントロールにフォーカスを移し(存在する場合)、終了する必要があります。
たとえば、directionが後方である場合、ブラウザのレンダリングエリアの前にある最後の順次フォーカス可能コントロールがフォーカスされるべきコントロールです。
ユーザーエージェントに順次フォーカス可能コントロールがない場合(たとえば、キオスクモードのブラウザなど)、ユーザーエージェントはstarting pointをトップレベルのトラバーサブル自体としてこれらの手順を再開始することができます。
それ以外の場合、starting pointは子ナビゲイブル内のフォーカス可能エリアであるため、starting pointをその子ナビゲイブルの親に設定し、ループというラベルが付いたステップに戻ります。
順次ナビゲーション検索アルゴリズムは、次の手順から構成されます。このアルゴリズムは、starting point、direction、およびselection mechanismの3つの引数を取ります。
次の表から適切なセルを選び、そのセルの指示に従います。
適切なセルは、列のヘッダーがdirectionを説明し、行のヘッダーがstarting pointとselection mechanismを説明する最初の行です。
| directionが前方 | directionが後方 | |
|---|---|---|
| starting pointがナビゲイブルである場合 | candidateをstarting pointのアクティブ文書内の最初の適切な順次フォーカス可能エリア、存在しない場合はnullとします | candidateをstarting pointのアクティブ文書内の最後の適切な順次フォーカス可能エリア、存在しない場合はnullとします |
| selection mechanismがDOMである場合 | candidateをstarting pointに続くホーム文書内の最初の適切な順次フォーカス可能エリア、存在しない場合はnullとします | candidateをstarting pointに先行するホーム文書内の最後の適切な順次フォーカス可能エリア、存在しない場合はnullとします |
| selection mechanismが順次である場合 | candidateをstarting pointに続くホーム順次フォーカスナビゲーション順序内の最初の適切な順次フォーカス可能エリア、存在しない場合はnullとします | candidateをstarting pointに先行するホーム順次フォーカスナビゲーション順序内の最後の適切な順次フォーカス可能エリア、存在しない場合はnullとします |
適切な順次フォーカス可能エリアとは、DOMアンカーがインアートでなく、順次フォーカス可能であるフォーカス可能エリアのことです。
ホーム文書とは、starting pointが属するDocumentのことです。
ホーム順次フォーカスナビゲーション順序とは、starting pointが属する順次フォーカスナビゲーション順序のことです。
ホーム順次フォーカスナビゲーション順序は、ホーム文書の順次フォーカスナビゲーション順序ですが、これはstarting pointがその順次フォーカスナビゲーション順序に含まれている場合にのみ使用されます(含まれていない場合、selection mechanismはDOMとなります)。
candidateが非nullのコンテンツナビゲイブルを持つナビゲイブルコンテナである場合、new candidateを、candidateのコンテンツナビゲイブルを最初の引数、directionを2番目の引数、順次を3番目の引数として順次ナビゲーション検索アルゴリズムを実行した結果とします。
new candidateがnullである場合、starting pointをcandidateとして、このアルゴリズムの最初に戻ります。それ以外の場合、candidateをnew candidateに設定します。
candidateを返します。
dictionary FocusOptions {
boolean preventScroll = false ;
boolean focusVisible ;
};
documentOrShadowRoot.activeElement
すべての現行エンジンでサポートされています。
すべての現行エンジンでサポートされています。
文書内でキーイベントがルーティングされる最も深い要素を返します。これは、概ね文書内のフォーカスされている要素です。
このAPIの目的では、子ナビゲイブルがフォーカスされている場合、そのコンテナがその親のアクティブ文書内でフォーカスされます。たとえば、ユーザーがiframe内のテキストコントロールにフォーカスを移動した場合、iframeがそのiframeのノード文書内でactiveElementAPIによって返される要素です。
同様に、フォーカスされている要素がdocumentOrShadowRootとは異なるノードツリー内にある場合、返される要素はdocumentOrShadowRootと同じノードツリーに位置するホストであり、documentOrShadowRootがそのフォーカスされた要素のシャドウを含む包括的祖先である場合に限りそうであり、そうでない場合はnullです。
document.hasFocus()
すべての現行エンジンでサポートされています。
キーイベントが文書を通過しているか、または文書に向かってルーティングされている場合はtrueを返します。そうでない場合はfalseを返します。大まかに言えば、これは文書自体、またはこの文書の内部にネストされている文書がフォーカスされていることを示します。
window.focus()
すべての現行エンジンでサポートされています。
ウィンドウのナビゲイブルにフォーカスを移動します(存在する場合)。
element.focus([ { preventScroll: true } ])
すべての現行エンジンでサポートされています。
要素にフォーカスを移動します。
要素がナビゲイブルコンテナである場合、フォーカスを代わりにそのコンテンツナビゲイブルに移動します。
デフォルトでは、このメソッドは要素をビューにスクロールします。オプションであるpreventScrollを指定してtrueに設定すると、この動作が防止されます。
element.blur()
すべての現行エンジンでサポートされています。
フォーカスをビューポートに移動します。このメソッドの使用は推奨されません。ビューポートにフォーカスを当てたい場合は、focus()メソッドをDocumentの文書要素に対して呼び出してください。
フォーカスリングが見苦しいと感じる場合に、このメソッドを使用してフォーカスリングを隠さないでください。代わりに、:focus-visible擬似クラスを使用して'アウトライン'プロパティを上書きし、フォーカスされている要素を示す別の方法を提供してください。代替のフォーカススタイルが提供されない場合、主にキーボードを使用してページをナビゲートする人々や、フォーカスアウトラインを使用してページをナビゲートする視覚障害のある人々にとって、ページは大幅に使いにくくなることに注意してください。
たとえば、textarea要素のアウトラインを非表示にし、代わりにフォーカスを示すために黄色の背景を使用するには、次のようにします:
textarea:focus-visible { outline : none; background : yellow; color : black; }
activeElement属性のゲッターは、以下の手順を実行しなければなりません:
candidateを、このDocumentOrShadowRootのノード文書のフォーカスされたエリアのDOMアンカーに設定します。
candidateを、このDocumentOrShadowRootに対してリターゲティングした結果に設定します。
candidateのルートがこのDocumentOrShadowRootでない場合、nullを返します。
candidateがDocumentオブジェクトでない場合、candidateを返します。
nullを返します。
hasFocus()メソッドは、Documentオブジェクトに対して実行された場合、そのDocumentオブジェクトを引数としてフォーカスがあるかの手順を実行した結果を返さなければなりません。
focus()メソッドが実行された場合、以下の手順を実行しなければなりません:
currentがnullの場合、終了します。
currentに対してフォーカス手順を実行します。
currentがトップレベルのトラバーサブルである場合、ユーザーエージェントはページがフォーカスを取得しようとしていることをユーザーに知らせる通知をトリガーすることが推奨されます。
すべての現行エンジンでサポートされています。
blur()メソッドの手順は何もしないことです。
歴史的に見て、focus()メソッドおよびblur()メソッドは、ナビゲイブルを含むシステムウィジェット(例:タブやウィンドウ)のシステムレベルのフォーカスに影響を与えていましたが、敵対的なサイトがこの動作を悪用してユーザーに悪影響を及ぼしていました。
focus(options)メソッドが要素で実行された場合、以下の手順を実行しなければなりません:
要素がフォーカスのためにロックされているとマークされている場合、終了します。
要素をフォーカスのためにロックされているとマークします。
要素に対してフォーカス手順を実行します。
もしoptionsのfocusVisible辞書メンバーの値がtrueであるか、または存在しないがユーザーエージェントが実装定義の方法でそれを行う方が最適であると判断した場合、フォーカスを示します。
もしoptionsのpreventScroll辞書メンバーの値がfalseである場合、「自動」、「中央」、「中央」を指定して要素をビューにスクロールします。
要素のフォーカスを解除します。
blur()メソッドが実行された場合、呼び出された要素に対してフォーカス解除手順を実行する必要があります。ユーザーエージェントは、使用可能性の理由から、このメソッドの呼び出しを選択的または一律に無視することができます。
例えば、blur()メソッドが美観上の理由でフォーカスリングを削除するために不適切に使用されている場合、ページはキーボードユーザーにとって使用不可能になります。このメソッドの呼び出しを無視することは、キーボードユーザーがページと対話できるようにするために役立ちます。
autofocus属性autofocusコンテンツ属性は、ページが読み込まれるとすぐに要素にフォーカスを当て、ユーザーが手動で主要な要素にフォーカスを当てなくても、すぐに入力を開始できるようにすることを著者に許可します。
autofocus属性がdialog要素やpopover属性が設定されたHTML要素内の要素に指定されている場合、そのダイアログやポップオーバーが表示されたときにフォーカスが当てられます。
Elementelementが与えられた場合の最も近い祖先のautofocusスコープのルート要素を見つけるには:
elementがdialog要素である場合、elementを返します。
elementのpopover属性がpopoverなしの状態でない場合、elementを返します。
ancestorをelementに設定します。
ancestorに親要素がある間:
ancestorをancestorの親要素に設定します。
ancestorがdialog要素である場合、ancestorを返します。
ancestorのpopover属性がpopoverなしの状態でない場合、ancestorを返します。
ancestorを返します。
最も近い祖先のautofocusスコープのルート要素を持つ2つの要素が両方ともautofocus属性を指定していてはなりません。
各Documentには、最初は空のautofocus候補リストがあります。
各Documentには、最初はfalseのautofocus処理済みフラグブール値があります。
autofocus属性が指定された要素が文書に挿入されるとき、次の手順を実行します:
ユーザーが(例えばフォームコントロールに入力を開始することで)フォーカスが変更されないことを望んでいることを示している場合は、任意で終了します。
targetを要素のノード文書に設定します。
targetが完全にアクティブでない場合、終了します。
targetのアクティブサンドボックスフラグセットがサンドボックス化された自動機能のブラウジングコンテキストフラグを持つ場合、終了します。
各 target の 祖先ナビゲーブル に対する ancestorNavigable について: ancestorNavigable の アクティブなドキュメント の オリジン が target の オリジン と 同一オリジン でない場合、処理を終了します。
topDocumentをtargetのノードナビゲイブルのトップレベルトラバース可能のアクティブ文書に設定します。
もしtopDocumentのautofocus処理済みフラグがfalseの場合、要素をtopDocumentのautofocus候補から削除し、要素をtopDocumentのautofocus候補に追加します。
要素がフォーカス可能領域であるかどうかは確認していません。これは、挿入時にはフォーカス可能領域でない場合でも、autofocus候補をフラッシュする際にフォーカス可能領域になる可能性があるためです。
文書topDocumentのautofocus候補をフラッシュするには、次の手順を実行します:
topDocumentのautofocus処理済みフラグがtrueの場合、終了します。
candidatesをtopDocumentのautofocus候補に設定します。
もしcandidatesが空の場合、終了します。
もしtopDocumentのフォーカスされた領域がtopDocument自体でないか、topDocumentが非nullのターゲット要素を持っている場合:
candidatesを空にします。
topDocumentのautofocus処理済みフラグをtrueに設定します。
終了します。
candidatesが空でない間:
elementをcandidates[0]に設定します。
docをelementのノード文書に設定します。
docのノードナビゲイブルのトップレベルトラバース可能がtopDocumentのノードナビゲイブルと同じでない場合、elementをcandidatesから削除し、続行します。
docのスクリプトブロッキングスタイルシートセットが空でない場合、終了します。
この場合、elementは現在の最良候補ですが、docは自動フォーカスの準備ができていません。autofocus候補をフラッシュが次に呼び出されたときに再試行します。
elementをcandidatesから削除します。
inclusiveAncestorDocumentsをdocの包括的祖先ナビゲイブルのアクティブ文書から成るリストに設定します。
もしinclusiveAncestorDocumentsのいずれかのDocumentに非nullのターゲット要素がある場合、続行します。
targetをelementに設定します。
もしtargetがフォーカス可能領域でない場合、targetをフォーカス可能領域を取得する結果に設定します。
autofocus候補には、フォーカス可能領域でない要素が含まれている場合があります。このような場合は、フォーカス可能領域を取得アルゴリズムで処理される特別なケースに加え、非フォーカス可能領域の要素が文書に挿入されたときに発生する可能性があり、それがフォーカス可能にならなかった場合、または要素がフォーカス可能であったがautofocus候補に保存されている間にステータスが変更されたためです。
もしtargetがnullでない場合、次を実行します:
candidatesを空にします。
topDocumentのautofocus処理済みフラグをtrueに設定します。
targetのフォーカスステップを実行します。
これは、文書の読み込み時に自動フォーカスを処理します。show()およびshowModal()のdialog要素も、autofocus属性を処理します。
要素にフォーカスを当てることは、ユーザーエージェントがブラウザウィンドウのフォーカスが失われた場合にフォーカスを当てる必要があることを意味しません。
一つのエンジンのみでサポートされています。
autofocusIDL属性は、同名のコンテンツ属性を反映しなければなりません。
次のスニペットでは、文書が読み込まれたときにテキストコントロールにフォーカスが当たります。
< input maxlength = "256" name = "q" value = "" autofocus >
< input type = "submit" value = "Search" >
autofocus属性は、フォームコントロールに限らず、すべての要素に適用されます。これにより、次のような例が可能になります:
< div contenteditable autofocus > Edit < strong > me!</ strong >< div >
このセクションは規範的ではありません。
アクティブ化またはフォーカスできる各要素には、accesskey
属性を使用して、それをアクティブ化するための単一のキーコンビネーションを割り当てることができます。
正確なショートカットは、ユーザーのキーボードに関する情報、プラットフォーム上で既に存在するキーボードショートカット、およびページ上で指定された他のショートカットに基づいて、ユーザーエージェントによって決定され、accesskey
属性で提供された情報をガイドとして使用します。
さまざまな入力デバイスで関連するキーボードショートカットが利用できるようにするために、著者はaccesskey
属性にいくつかの代替案を提供することができます。
各代替案は、文字や数字などの単一の文字で構成されます。
ユーザーエージェントはユーザーにキーボードショートカットのリストを提供することができますが、著者もそれを行うことが推奨されます。accessKeyLabel IDL
属性は、
ユーザーエージェントによって割り当てられた実際のキーコンビネーションを表す文字列を返します。
この例では、著者はショートカットキーを使用して呼び出すことができるボタンを提供しています。フルキーボードをサポートするために、著者は「C」を可能なキーとして提供しています。数字キーパッドのみを装備したデバイスをサポートするために、著者は「1」を別の可能なキーとして提供しています。
< input type = button value = Collect onclick = "collect()"
accesskey = "C 1" id = c >
ショートカットキーが何であるかをユーザーに知らせるために、著者はこのスクリプトでキーコンビネーションをボタンのラベルに明示的に追加することを選択しています:
function addShortcutKeyLabel( button) {
if ( button. accessKeyLabel != '' )
button. value += ' (' + button. accessKeyLabel + ')' ;
}
addShortcutKeyLabel( document. getElementById( 'c' ));
異なるプラットフォームのブラウザでは、同じキーコンビネーションでも異なるラベルが表示されます。例えば、キーコンビネーションがControlキー、Shiftキー、Cキーの場合、Windowsブラウザでは"Ctrl+Shift+C"、Macブラウザでは"^⇧C"、Emacsブラウザでは"C-C"と表示されるかもしれません。同様に、キーコンビネーションがAltキーとEscapeキーの場合、Windowsでは"Alt+Esc"、Macでは"⌥⎋"、Emacsブラウザでは"M-ESC"または"ESC ESC"が表示されるかもしれません。
したがって、一般的には、accessKeyLabel IDL
属性から返される値を解析しようとすることは賢明ではありません。
accesskey
属性現在のすべてのエンジンでサポートされています。
すべての HTML 要素 は、accesskey
コンテンツ属性を設定できます。この accesskey
属性の値は、ユーザーエージェントが要素をアクティブ化またはフォーカスするためのキーボードショートカットを作成するためのガイドとして使用されます。
指定されている場合、その値は一意のスペースで区切られたトークンの順序セットでなければならず、 いずれも別のトークンと同一であってはならず、それぞれが正確に1つの コードポイントの長さでなければなりません。
次の例では、サイトに精通しているキーボードユーザーが関連するページにより迅速に移動できるように、さまざまなリンクにアクセスキーが割り当てられています:
< nav >
< p >
< a title = "Consortium Activities" accesskey = "A" href = "/Consortium/activities" > Activities</ a > |
< a title = "Technical Reports and Recommendations" accesskey = "T" href = "/TR/" > Technical Reports</ a > |
< a title = "Alphabetical Site Index" accesskey = "S" href = "/Consortium/siteindex" > Site Index</ a > |
< a title = "About This Site" accesskey = "B" href = "/Consortium/" > About Consortium</ a > |
< a title = "Contact Consortium" accesskey = "C" href = "/Consortium/contact" > Contact</ a >
</ p >
</ nav >
次の例では、検索フィールドに「s」と「0」(この順序で)の2つのアクセスキーが割り当てられています。フルキーボードを備えたデバイスのユーザーエージェントは、ショートカットキーとして Ctrl + Alt + S を選択するかもしれませんが、数字キーパッドのみを備えた小型デバイスのユーザーエージェントは、単純に 0 のキーを選択するかもしれません:
< form action = "/search" >
< label > Search: < input type = "search" name = "q" accesskey = "s 0" ></ label >
< input type = "submit" >
</ form >
次の例では、ボタンにアクセスキーが設定されています。次に、スクリプトがボタンのラベルを更新し、ユーザーエージェントが選択したキーコンビネーションを表示しようとします。
< input type = submit accesskey = "N @ 1" value = "Compose" >
...
< script >
function labelButton( button) {
if ( button. accessKeyLabel)
button. value += ' (' + button. accessKeyLabel + ')' ;
}
var inputs = document. getElementsByTagName( 'input' );
for ( var i = 0 ; i < inputs. length; i += 1 ) {
if ( inputs[ i]. type == "submit" )
labelButton( inputs[ i]);
}
</ script >
あるユーザーエージェントでは、ボタンのラベルが「Compose (⌘N)」になるかもしれません。別のユーザーエージェントでは、「Compose (Alt+⇧+1)」になるかもしれません。ユーザーエージェントがキーを割り当てない場合は、単に「Compose」のままになります。正確な文字列は、割り当てられたアクセスキーと、ユーザーエージェントがそのキーコンビネーションをどのように表現するかに依存します。
要素の割り当てられたアクセスキーは、その要素のaccesskey
コンテンツ属性から派生したキーコンビネーションです。初期状態では、要素には割り当てられたアクセスキーが存在してはなりません。
要素のaccesskey
属性が設定、変更、または削除されるたびに、ユーザーエージェントは以下の手順を実行して要素の割り当てられたアクセスキーを更新しなければなりません:
要素にaccesskey
属性がない場合は、以下のフォールバックステップに進みます。
それ以外の場合は、属性の値をASCIIホワイトスペースで分割し、keysを得たトークンとします。
keysの各値について、属性の値に表示された順序で次のサブステップを順に実行します:
その値が正確に1コードポイントの長さでない場合、この値についての残りの手順をスキップします。
その値がシステムのキーボード上のキーに対応しない場合、この値についての残りの手順をスキップします。
ユーザーエージェントが、属性で指定された値に対応するキーと組み合わせて使用できる0個以上の修飾キーを見つけることができる場合、ユーザーエージェントはそのキーの組み合わせを要素の割り当てられたアクセスキーとして割り当てることができ、その時点で終了します。
フォールバック: 任意で、ユーザーエージェントは自分で選択したキーコンビネーションを要素の割り当てられたアクセスキーとして割り当てることができ、その後終了します。
このステップに到達した場合、要素には割り当てられたアクセスキーが存在しません。
ユーザーエージェントが要素にアクセスキーを選択して割り当てた後は、accesskey
コンテンツ属性が変更されるか、要素が別のドキュメントに移動されない限り、ユーザーエージェントはその要素の割り当てられたアクセスキーを変更すべきではありません。
ユーザーが要素に対する割り当てられたアクセスキーに対応するキーコンビネーションを押すと、要素がコマンドを定義し、コマンドののファセットが偽(表示)であり、コマンドの無効状態のファセットも偽(有効)であり、要素がドキュメント内にあり、非nullのブラウジングコンテキストを持ち、要素自身およびその祖先のいずれにも属性が指定されていない場合、ユーザーエージェントはコマンドのアクションをトリガーしなければなりません。
ユーザーエージェントは、accesskey属性を持つ要素を、特定のキーコンビネーションに応じて表示されるメニューなど、他の方法でも公開することがあります。
現在のすべてのエンジンでサポートされています。
The accessKey
IDL属性は、accesskey
コンテンツ属性を反映しなければなりません。
accessKeyLabel
IDL属性は、要素に割り当てられたアクセスキーを表す文字列を返さなければなりません。要素にアクセスキーがない場合、このIDL属性は空の文字列を返さなければなりません。
contenteditable
コンテンツ属性すべての現在のエンジンでサポートされています。
interface mixin ElementContentEditable {
[CEReactions ] attribute DOMString contentEditable ;
[CEReactions ] attribute DOMString enterKeyHint ;
readonly attribute boolean isContentEditable ;
[CEReactions ] attribute DOMString inputMode ;
};
Global_attributes/contenteditable
すべての現在のエンジンでサポートされています。
この contenteditable コンテンツ属性は、列挙属性であり、次のキーワードと状態を持ちます:
| キーワード | 状態 | 簡潔な説明 |
|---|---|---|
true
| true | この要素は編集可能です。 |
| (空の文字列) | ||
false
| false | この要素は編集不可です。 |
plaintext-only
| plaintext-only | 要素の生テキストコンテンツのみが編集可能であり、リッチなフォーマットは無効です。 |
属性の 欠損値デフォルト と 無効値デフォルト はどちらも inherit 状態です。
この
inherit 状態は、親要素の状態に基づいて要素が編集可能かどうかを示します。
例えば、HTML を使用して記事を書いて新しい記事を公開することを想定して、フォーム と テキストエリア を含むページを考えてみます:
< form method = POST >
< fieldset >
< legend > 新しい記事</ legend >
< textarea name = article > < p>こんにちは、世界。< /p></ textarea >
</ fieldset >
< p >< button > 公開</ button ></ p >
</ form >
スクリプトが有効になっている場合、テキストエリア
要素
は、contenteditable
属性を使用して、リッチテキストコントロールに置き換えることができます:
< form method = POST >
< fieldset >
< legend > 新しい記事</ legend >
< textarea id = textarea name = article > < p>こんにちは、世界。< /p></ textarea >
< div id = div style = "white-space: pre-wrap" hidden >< p > こんにちは、世界。</ p ></ div >
< script >
let textarea = document. getElementById( "textarea" );
let div = document. getElementById( "div" );
textarea. hidden = true ;
div. hidden = false ;
div. contentEditable = "true" ;
div. oninput = ( e) => {
textarea. value = div. innerHTML;
};
</ script >
</ fieldset >
< p >< button > 公開</ button ></ p >
</ form >
リンク挿入などの機能を有効にすることは、document.execCommand()
API、または
Selection
API とその他の DOM API を使用して実装できます。[EXECCOMMAND] [SELECTION]
[DOM]
この contenteditable
属性も効果的に使用できます:
<!doctype html>
< html lang = en >
< title > ライブCSS編集!</ title >
< style style = white-space:pre contenteditable >
html { margin : .2 em ; font-size : 2 em ; color : ライム ; background : 紫 }
head , title , style { display : ブロック }
body { display : なし }
</ style >
element.contentEditable [ = value ]
現在の状態に基づき、"true"、"plaintext-only"、"false"、または "inherit"
を返します。
この状態を変更するために設定できます。
新しい値がこれらの文字列のいずれかでない場合、"SyntaxError" DOMException
をスローします。
element.isContentEditable
すべての現在のエンジンでサポートされています。
要素が編集可能である場合に true を返し、それ以外の場合は false を返します。
この contentEditable IDL属性は、取得時に、true
状態に設定されている場合は文字列 "true" を、
plaintext-only 状態に設定されている場合は
"plaintext-only" を、
false
状態に設定されている場合は "false" を返し、
それ以外の場合は "inherit"
を返す必要があります。設定時には、新しい値が "inherit" に対して ASCII
大文字小文字を区別しない 一致する場合、content 属性を削除する必要があります。
新しい値が "true" に対して ASCII
大文字小文字を区別しない 一致する場合、content 属性を "true" の文字列に設定する必要があります。
新しい値が "plaintext-only" に対して ASCII
大文字小文字を区別しない 一致する場合、content 属性を "plaintext-only" の文字列に設定する必要があります。
新しい値が "false" に対して ASCII
大文字小文字を区別しない 一致する場合、content 属性を "false" の文字列に設定する必要があります。
それ以外の場合、属性セッターは "SyntaxError" DOMException
をスローしなければなりません。
この isContentEditable IDL 属性は、取得時に、要素が 編集ホスト
または 編集可能 である場合に true を返し、
それ以外の場合は false を返さなければなりません。
designMode
getterおよびsetter
document.designMode [ = value ]
すべての現在のエンジンでサポートされています。
ドキュメントが編集可能な場合は "on" を返し、そうでない場合は "off" を返します。
設定することで、ドキュメントの現在の状態を変更できます。これにより、ドキュメントがフォーカスされ、そのドキュメント内の選択がリセットされます。
Document
オブジェクトには、デザインモードが有効 という関連付けられたブール値があります。初期状態は false です。
designMode getter ステップは、this の デザインモードが有効 である場合は
"on" を返し、そうでない場合は "off" を返します。
designMode
setter ステップは次のとおりです:
与えられた値を ASCII 小文字に変換し、その値を value とします。
もし value が "on" であり、this の デザインモードが有効
が false である場合は:
もし value が "off" である場合は、this の
デザインモードが有効
を false に設定します。
著者は、'white-space' プロパティを編集ホストおよびこれらの編集メカニズムを通じて作成されたマークアップに 'pre-wrap' の値を設定することが推奨されます。デフォルトのHTML空白処理はWYSIWYG編集に適しておらず、'white-space' をデフォルト値のままにしておくと、いくつかのコーナーケースでは行の折り返しが正しく機能しない場合があります。
デフォルトの 'normal' 値が使用された場合に発生する問題の例として、ユーザーが「yellow␣␣ball」と入力したケースを考えてみます。ここでは、単語間に2つのスペース("␣" で表現)があるとします。'white-space' ('normal') のデフォルト値に基づく編集ルールでは、生成されるマークアップは "yellow ball" または "yellow ball" のいずれかになります。つまり、通常のスペースに加えて、2つの単語の間にノンブレーキングスペースが追加されます。これは、'white-space' の 'normal' 値が、隣接する通常のスペースを一緒に折り畳むことを要求するためです。
前者の場合、"yellow⍽" は次の行に折り返される可能性があります(ここでは "⍽" がノンブレーキングスペースを表しています)が、"yellow" だけであれば行末に収まる可能性があります。後者の場合、"⍽ball" が行の先頭に折り返された場合、ノンブレーキングスペースによる目に見えるインデントが残ります。
しかし、'white-space' が 'pre-wrap' に設定されている場合、編集ルールは代わりに単語間に2つの通常のスペースを配置し、もし2つの単語が行末で分割された場合、そのスペースはレンダリングからきれいに除去されます。
編集ホストとは、contenteditable属性がtrueまたはplaintext-onlyの状態にあるHTML要素、または子のHTML要素で、そのデザインモードが有効なDocumentを指します。
用語の定義については、アクティブ範囲、編集ホストの、および編集可能、編集ホストまたは編集可能な要素のユーザーインターフェース要件、execCommand()、queryCommandEnabled()、queryCommandIndeterm()、queryCommandState()、queryCommandSupported()、およびqueryCommandValue()のメソッド、テキスト選択、および選択を削除するアルゴリズムについてはexecCommandに定義されています。[EXECCOMMAND]
ユーザーエージェントは、フォームコントロール内のテキスト(例えば、textarea要素の値)や、編集ホスト内の要素におけるテキストのスペルおよび文法のチェックをサポートすることができます(例:contenteditableを使用)。
各要素に対して、ユーザーエージェントはデフォルトの動作を確立しなければなりません。これはデフォルト値またはユーザーによって設定された好みを通じて表現されます。各要素には次の3つのデフォルトの動作が考えられます。
spellcheck属性によってスペルチェックが明示的に無効化されていない場合、その要素のスペルと文法はチェックされます。
spellcheck属性を通じて明示的に有効化されない限り、チェックされません。
すべての現在のエンジンでサポートされています。
spellcheck属性は、次のキーワードと状態を持つ列挙型属性です。
| キーワード | 状態 | 簡潔な説明 |
|---|---|---|
true
| true | スペルおよび文法がチェックされます。 |
| (空の文字列) | ||
false
| false | スペルおよび文法はチェックされません。 |
この属性の欠落値のデフォルトおよび無効値のデフォルトはどちらもデフォルト状態です。デフォルト状態は、要素が親要素のspellcheck状態に基づいて動作することを示します。
element.spellcheck [ = value ]
要素のスペルおよび文法がチェックされる場合はtrueを返し、それ以外の場合はfalseを返します。
設定すると、デフォルトを無効にし、spellcheckコンテンツ属性を設定します。
spellcheckIDL属性は、取得時に、要素のspellcheckコンテンツ属性がtrue状態にある場合、または要素のspellcheckコンテンツ属性がデフォルト状態にあり、要素のデフォルト動作がtrue-by-defaultである場合、または要素のspellcheckコンテンツ属性がデフォルト状態にあり、要素のデフォルト動作がinherit-by-defaultであり、親要素のspellcheckIDL属性がtrueを返す場合にtrueを返さなければなりません。それ以外の場合、この属性はfalseを返す必要があります。
spellcheckIDL属性は、ユーザーの設定によってspellcheckコンテンツ属性を上書きした場合には影響を受けないため、実際のスペルチェック状態を反映していない場合があります。
設定する場合、新しい値がtrueであれば、要素のspellcheckコンテンツ属性は「true」に設定され、そうでない場合は「false」に設定されなければなりません。
ユーザーエージェントは、この機能の目的で次のテキストのみをチェック可能とみなすべきです。
input要素のvalueであり、type属性がText、Search、URL、またはEmail状態にあり、mutable(すなわち、readonly属性が指定されておらず、無効でない)要素。textarea要素のvalueであり、readonly属性が指定されておらず、無効でない要素。Textノードであり、編集ホストまたは編集可能な要素の子要素。Textノードに含まれるテキストの場合、そのテキストが関連付けられている要素は、単語、文、またはその他のテキストの最初の文字の直近の親要素です。属性内のテキストの場合、それは属性の要素です。inputおよびtextarea要素の値については、それは要素自体です。
適用可能な要素内(上記で定義)の単語、文、またはその他のテキストのスペルおよび文法のチェックを有効にするかどうかを判断するには、UAは次のアルゴリズムを使用しなければなりません。
spellcheckコンテンツ属性がある場合、その属性がtrue状態であればチェックは有効になり、それ以外の場合、その属性がfalse状態であればチェックは無効になります。spellcheckコンテンツ属性を持つ祖先要素がある場合、最も近いそのような祖先のspellcheckコンテンツ属性がtrue状態であればチェックは有効になり、それ以外の場合、チェックは無効になります。
チェックが単語/文/テキストに対して有効である場合、ユーザーエージェントはそのテキストにスペルおよび文法エラーを示すべきです。ユーザーエージェントは、スペルおよび文法修正を提案する際に、文書に指定された他のセマンティクスを考慮に入れるべきです。ユーザーエージェントは、要素の言語を使用して適用すべきスペルおよび文法ルールを決定するか、ユーザーの好みの言語設定を使用するかもしれません。UAは、input要素のpatternなどの属性を使用して、可能な限り結果として得られる値が有効であることを確認すべきです。
チェックが無効になっている場合、ユーザーエージェントはそのテキストに対してスペルまたは文法エラーを示すべきではありません。
次の例で「a」のIDを持つ要素は、「Hello」という単語のスペルエラーをチェックするかどうかを決定するために使用されます。この例では、チェックはされません。
< div contenteditable = "true" >
< span spellcheck = "false" id = "a" > Hell</ span >< em > o!</ em >
</ div >
次の例で「b」のIDを持つ要素にはチェックが有効になります(input要素の属性値の先頭にある空白文字が属性を無効にするため、デフォルトに関係なく祖先の値が代わりに使用されます)。
< p spellcheck = "true" >
< label > Name: < input spellcheck = " false" id = "b" ></ label >
</ p >
この仕様は、スペルおよび文法チェックのためのユーザーインターフェイスを定義していません。ユーザーエージェントは、必要に応じてチェックを提供するか、チェックが有効になっている場合には継続的にチェックを実行するか、または他のインターフェイスを使用することができます。
ユーザーエージェントは、フォームコントロール(例:textarea要素)や編集ホスト内の要素に対して、ユーザーが編集可能な領域に入力する際に書き込み提案を提供します。
writingsuggestionsコンテンツ属性は、以下のキーワードと状態を持つ列挙属性です。
| キーワード | 状態 | 簡潔な説明 |
|---|---|---|
true
| true | この要素に書き込み提案を提供するべきです。 |
| (空文字列) | ||
false
| false | この要素に書き込み提案を提供しないべきです。 |
属性の欠落値のデフォルトはデフォルト状態です。このデフォルト状態は、要素が、以下に定義されるように、親要素のwritingsuggestions状態に基づいてデフォルトの動作に従うことを示します。
属性の無効な値のデフォルトは、true状態です。
element.writingSuggestions [ = value ]
ユーザーエージェントが要素の範囲内で書き込み提案を提供する場合、"true"を返し、それ以外の場合、"false"を返します。
デフォルトを上書きしてwritingsuggestionsコンテンツ属性を設定することができます。
指定されたelementの計算された書き込み提案値は、次の手順を実行することで決定されます。
もしelementのwritingsuggestionsコンテンツ属性がfalse状態にある場合、"false"を返します。
もしelementのwritingsuggestionsコンテンツ属性がデフォルト状態にあり、elementに親要素があり、親要素の計算された書き込み提案値が"false"である場合、"false"を返します。
"true"を返します。
writingSuggestionsのgetterの手順は次のとおりです。
この要素の計算された書き込み提案値を返します。
writingSuggestionsIDL属性は、writingsuggestionsコンテンツ属性を上書きするユーザーの設定によって影響を受けず、実際の書き込み提案状態を反映していない場合があります。
writingSuggestionsのsetterの手順は次のとおりです。
この要素のwritingsuggestionsコンテンツ属性に指定された値を設定します。
ユーザーエージェントは、次のアルゴリズムを実行した結果がtrueを返す場合にのみ、要素の範囲内で提案を提供すべきです。
ユーザーが書き込み提案を無効にしている場合、falseを返します。
次の条件がいずれもtrueでない場合:
falseを返します。
もしelementに包括祖先があり、そのwritingsuggestionsコンテンツ属性がデフォルトではなく、最も近いその祖先のwritingsuggestionsコンテンツ属性がfalse状態である場合、falseを返します。
それ以外の場合、trueを返します。
この仕様は、書き込み提案のためのユーザーインターフェイスを定義していません。ユーザーエージェントは、必要に応じて提案を提供するか、ユーザーが入力するたびに継続的に提案を行うか、インライン提案やポップアップでの自動入力のような提案を行うか、または他のインターフェイスを使用することができます。
一部のテキスト入力方法、例えばモバイルデバイスの仮想キーボードや音声入力は、しばしばユーザーを支援するために、文の最初の文字を自動的に大文字にします(この習慣のある言語でテキストを作成する場合)。自動大文字化を実装した仮想キーボードは、大文字にすべき文字が入力される直前に、自動的に大文字を表示するように切り替えるかもしれません(ただし、ユーザーはこれを小文字に戻すこともできます)。他のタイプの入力、例えば音声入力では、ユーザーが介入するオプションを提供せずに自動大文字化を実行することがあります。autocapitalize属性は、著者がそのような動作を制御するために使用できます。
autocapitalize属性は、通常、物理キーボードでの入力時には動作に影響を与えません。(このため、およびユーザーが一部のケースで自動大文字化の動作を上書きしたり、初期入力後にテキストを編集する可能性があるため、この属性に基づいて入力の検証を行うべきではありません。)
autocapitalize属性は、ホストされた編集可能な領域に対して自動大文字化の動作を制御するために編集ホストに使用したり、input要素やtextarea要素に使用してその要素へのテキスト入力の動作を制御したり、フォーム要素に使用してそのフォームに関連付けられたすべての自動大文字化を継承する要素に対するデフォルトの動作を制御できます。
autocapitalize属性は、input要素のtype属性がURL、Email、またはPasswordのいずれかの状態にある場合、決して自動大文字化を有効にしません。(この動作は、以下の使用される自動大文字化ヒントアルゴリズムに含まれています。)
自動大文字化処理モデルは、以下の5つの自動大文字化ヒントの中から選択することに基づいています:
ユーザーエージェントおよび入力方法は、自動大文字化を有効にするかどうかを独自に判断すべきです。
自動大文字化は適用されないべきです(すべての文字は小文字をデフォルトにすべきです)。
各文の最初の文字は大文字をデフォルトにし、その他の文字は小文字をデフォルトにすべきです。
各単語の最初の文字は大文字をデフォルトにし、その他の文字は小文字をデフォルトにすべきです。
すべての文字は大文字をデフォルトにすべきです。
Global_attributes/autocapitalize
すべての現行エンジンでサポートされています。
autocapitalize属性は、次の自動大文字化ヒントの状態を持つ列挙属性です。属性の状態によって指定された自動大文字化ヒントは、その他の考慮事項と組み合わさって使用される自動大文字化ヒントを形成し、ユーザーエージェントの動作に影響を与えます。以下に、この属性のキーワードとその状態のマッピングを示します:
| キーワード | 状態 |
|---|---|
off
| なし |
none
| |
on
| 文 |
sentences
| |
words
| 単語 |
characters
| 文字 |
この属性の欠損値デフォルトはデフォルト状態であり、無効値デフォルトは文状態です。
element.autocapitalize [ = value ]
要素の現在の自動大文字化状態を返します。設定されていない場合は空の文字列を返します。input要素およびtextarea要素がその状態をフォーム要素から継承する場合、これはフォーム要素の自動大文字化状態を返しますが、編集可能な領域の要素の場合、これは編集ホストの自動大文字化状態を返しません(この要素が実際には編集ホストでない限り)。
設定すると、autocapitalizeコンテンツ属性を設定し(その結果、要素の自動大文字化動作が変更されます)。
要素elementの独自の自動大文字化ヒントを計算するには、次のステップを実行します:
もしautocapitalizeコンテンツ属性がelementに存在し、その値が空文字列でない場合、その属性の状態を返します。
element が 自動大文字変換を継承する要素 であり、非 null の フォーム所有者 を持つ場合、element の フォーム所有者 の自身の自動大文字変換ヒント を返します。
デフォルトを返します。
autocapitalizeゲッターステップは次の通りです:
stateを独自の自動大文字化ヒントとし、thisの値とします。
stateがデフォルトである場合、空の文字列を返します。
stateに対応するキーワード値を返します。
autocapitalizeセッターステップは、autocapitalizeコンテンツ属性に指定された値を設定します。
テキスト入力方法に対してカスタマイズ可能な自動大文字化動作をサポートし、Web開発者がこの機能を制御できるようにしたいユーザーエージェントは、要素へのテキスト入力中にその要素の使用される自動大文字化ヒントを計算する必要があります。これは、要素にテキストを入力する際の推奨される自動大文字化動作を説明する自動大文字化ヒントです。
ユーザーエージェントや入力方法は、特定の状況で使用される自動大文字化ヒントを無視または上書きすることを選択できます。
要素elementの使用される自動大文字化ヒントは、次のアルゴリズムを使用して計算されます:
もしelementがinput要素であり、そのtype属性がURL、Email、またはPasswordのいずれかの状態にある場合、デフォルトを返します。
もしelementがinput要素またはtextarea要素である場合、elementの独自の自動大文字化ヒントを返します。
もしelementが編集ホストまたは編集可能要素である場合、その要素の独自の自動大文字化ヒントを返します。
アサート:このステップには決して到達しません。なぜなら、テキスト入力は上記の基準のいずれかを満たす要素にのみ発生するからです。
inputmode
属性ユーザーエージェントは、フォームコントロール(textarea
要素など)のinputmode
属性、または編集ホスト内の要素(例: contenteditable
を使用して)をサポートできます。
すべての現在のエンジンでサポートされています。
inputmode
コンテンツ属性は、ユーザーがコンテンツを入力する際に最も役立つ入力メカニズムを指定する列挙型属性です。
| キーワード | 説明 |
|---|---|
none
| ユーザーエージェントは仮想キーボードを表示しないようにします。このキーワードは、独自のキーボードコントロールをレンダリングするコンテンツに適しています。 |
text
| ユーザーエージェントは、ユーザーのロケールにおいてテキスト入力が可能な仮想キーボードを表示する必要があります。 |
tel
| ユーザーエージェントは電話番号入力が可能な仮想キーボードを表示する必要があります。これには、0から9までの数字キー、「#」文字、および「*」文字を含むべきです。一部の地域では、これにアルファベットのニーモニックラベルも含めることがあります(例: 米国では、「2」キーは歴史的にA、B、Cの文字が付けられています)。 |
url
| ユーザーエージェントは、ユーザーのロケールにおいてテキスト入力が可能な仮想キーボードを表示する必要があり、URLの入力を補助するキー(例: 「/」文字や「.」文字、または「www.」や「.com」などのドメイン名によく見られる文字列のクイック入力のためのキー)を含める必要があります。 |
email
| ユーザーエージェントは、ユーザーのロケールにおいてテキスト入力が可能な仮想キーボードを表示する必要があり、メールアドレスの入力を補助するキー(例: 「@」文字や「.」文字)を含める必要があります。 |
numeric
| ユーザーエージェントは、数値入力が可能な仮想キーボードを表示する必要があります。このキーワードは、PIN入力に役立ちます。 |
decimal
| ユーザーエージェントは、小数入力が可能な仮想キーボードを表示する必要があります。数値キーとロケールに適したフォーマットセパレータが表示されるべきです。 |
search
| ユーザーエージェントは、検索に最適化された仮想キーボードを表示する必要があります。 |
すべての現在のエンジンでサポートされています。
inputMode
IDL属性は、inputmode
コンテンツ属性を反映する必要があり、既知の値のみに制限されます。
inputmode
が指定されていない場合(またはユーザーエージェントでサポートされていない状態の場合)、ユーザーエージェントは表示されるデフォルトの仮想キーボードを決定する必要があります。入力type
またはpattern属性などのコンテキスト情報を使用して、表示されるべき仮想キーボードの種類を判断する必要があります。
enterkeyhint
属性
ユーザーエージェントは、フォームコントロール(textarea
要素など)のenterkeyhint
属性、または編集ホスト内の要素(例: contenteditableを使用して)をサポートできます。
Global_attributes/enterkeyhint
すべての現在のエンジンでサポートされています。
enterkeyhintコンテンツ属性は、仮想キーボードのエンターキーに提示するアクションラベル(またはアイコン)を指定する列挙型属性です。これにより、エンターキーの表示をカスタマイズし、ユーザーにとってより役立つものにすることができます。
| キーワード | 説明 |
|---|---|
enter
| ユーザーエージェントは、「enter」の操作のためのキューを提示する必要があります。通常、新しい行を挿入します。 |
done
| ユーザーエージェントは、「done」の操作のためのキューを提示する必要があります。通常、入力するものがなく、入力方法エディタ(IME)が閉じられることを意味します。 |
go
| ユーザーエージェントは、「go」の操作のためのキューを提示する必要があります。通常、ユーザーを入力したテキストのターゲットに連れて行くことを意味します。 |
next
| ユーザーエージェントは、「next」の操作のためのキューを提示する必要があります。通常、ユーザーを次のテキストを受け入れるフィールドに移動させます。 |
previous
| ユーザーエージェントは、「previous」の操作のためのキューを提示する必要があります。通常、ユーザーを前のテキストを受け入れるフィールドに移動させます。 |
search
| ユーザーエージェントは、「search」の操作のためのキューを提示する必要があります。通常、ユーザーを入力したテキストの検索結果に連れて行きます。 |
send
| ユーザーエージェントは、「send」の操作のためのキューを提示する必要があります。通常、テキストをそのターゲットに送信します。 |
すべての現在のエンジンでサポートされています。
enterKeyHint IDL属性は、enterkeyhint
コンテンツ属性を反映し、既知の値のみに制限されます。
enterkeyhint
が指定されていない場合(またはユーザーエージェントでサポートされていない状態の場合)、ユーザーエージェントは提示するデフォルトのアクションラベル(またはアイコン)を決定する必要があります。inputmode、
type、
またはpattern
属性などのコンテキスト情報を使用して、仮想キーボードに提示するアクションラベル(またはアイコン)を決定する必要があります。
このセクションでは、ページ内検索について定義します。これは、ユーザーが特定の情報を探すために、ページの内容を検索できる一般的なユーザーエージェントのメカニズムです。
ページ内検索機能へのアクセスは、ページ内検索インターフェースを介して提供されます。これは、ユーザーが入力と検索のパラメータを指定できるユーザーエージェントが提供するユーザーインターフェースです。このインターフェースは、ショートカットやメニュー選択の結果として表示されることがあります。
ページ内検索インターフェースでのテキスト入力と設定の組み合わせが、ユーザーのクエリを表します。これには通常、ユーザーが検索したいテキストと、検索を単語全体のみに制限するオプション設定などが含まれます。
ユーザーエージェントは、与えられたクエリに対してページ内容を処理し、ユーザーのクエリを満たす0個以上の一致を特定します。
これらの一致のうちの1つが、ユーザーにアクティブ一致として識別されます。これは強調表示され、表示領域にスクロールされます。ユーザーはページ内検索インターフェースを使用して、アクティブ一致を進めることで、一致をナビゲートできます。
Issue #3539は、現在未定義のwindow.find()
APIの基盤としてページ内検索が標準化されるかどうかを追跡しています。
ページ内検索が一致する項目を検索し始めるとき、ページ内のすべての要素で、 属性が設定されていないものは、 の第2スロットがアクセス可能になるべきです。ただし、属性は変更されず、 これによりページ内検索がその内容を検索できるようにします。同様に、状態の 属性を持つすべてのHTML要素も、 がアクセス可能になり、ページ内検索がそれらを検索できるようになります。ページ内検索が一致する項目の検索を終了すると、 要素と、 状態の属性を持つ要素の内容は再びスキップされるべきです。このプロセス全体は同期的に行われる必要があり(したがって、ユーザーや著者コードには観察されません)。[CSSCONTAIN]
ページ内検索が新しいを選択すると、次の手順を実行します。
nodeをの最初のノードに設定します。
し、 に基づいて、nodeのに次の手順を実行するようにします。
nodeに対してを実行します。
nodeに対してを実行します。
ページ内検索がこのように要素を自動的に展開すると、 イベントが発生します。 ページ内検索が発生する別のイベントと同様に、このイベントは ページがユーザーがページ内検索ダイアログに入力している内容を検出するために使用される可能性があります。ページが現在の検索語とユーザーが入力する可能性のあるすべての次の文字を小さなスクロール可能領域に表示し、どれがブラウザによってスクロールされたかを観察することで、その文字を検索語に追加し、検索語を段階的に構築するためにスクロール可能な領域を更新できます。次の一致をそれぞれ閉じた要素でラップすることで、ページはイベントを使用してイベントの代わりにイベントをリッスンできます。この攻撃は、ユーザーがページ内検索ダイアログに入力するすべての文字に対して動作しないようにすることで、両方のイベントに対処できる可能性があります。
ページ内検索プロセスはドキュメントのコンテキストで呼び出され、そのドキュメントの選択に影響を与える可能性があります。具体的には、アクティブ一致を定義する範囲が現在の選択を決定する場合があります。ただし、これらの選択更新はページ内検索プロセスの異なるタイミング(例:ページ内検索インターフェースの解除時や、アクティブ一致範囲の変更時)に発生することがあります。
実装依存(おそらくデバイス固有の方法)で、 ユーザーは 閉じるリクエストをユーザーエージェントに送信できます。これは、 ユーザーが現在画面に表示されているもの(ポップオーバー、メニュー、ダイアログ、ピッカー、または表示モードなど)を閉じたいことを示します。
いくつかの例としては、以下のような閉じるリクエストがあります:
デスクトッププラットフォームでの Esc キー。
Androidなどの特定のモバイルプラットフォームでの戻るボタンまたはジェスチャー。
iOSのVoiceOverのような支援技術による閉じるジェスチャー、例えば二本指での「z」ジェスチャー。
DualShock ゲームパッドのサークルボタンなどのゲームコントローラーの標準「戻る」ボタン。
ユーザーエージェントが Document
document に対する潜在的な閉じるリクエストを受信した場合、グローバルタスクをキューイングする必要があります。
ユーザーインタラクションタスクソースの
document の 関連グローバルオブジェクトで、以下の 閉じるリクエスト手順 を実行します:
document の 全画面要素 が null でない場合、次のようにします:
全画面を完全に終了します document の ノードナビゲーブル の 最上位 トラバース可能 の アクティブな ドキュメント に対して。
戻ります。
この操作は、keydown
などの関連イベントを発火させることはありません。
ただし、fullscreenchange
イベントが最終的に発火することがあります。
オプションとして、代替処理 のステップにスキップします。
例えば、ユーザーエージェントが現在のウェブページによる繰り返しの閉じるリクエストの干渉に対するユーザーのフラストレーションを検出した場合、こちらの処理に進むかもしれません。
UI Events またはその他の関連仕様に従って、関連するイベントを発火させます。 [UIEVENTS]
例えば、UI Events モデルでは、ユーザーがキーボードの Esc キーを押したときに発火するイベントとして
keydown
が考えられます。ほとんどのキーボードプラットフォームでは、これは 閉じるリクエスト
として扱われ、これらの 閉じるリクエスト手順 をトリガーします。
UI Events モデル外の関連イベントの例としては、支援技術がユーザーが閉じるジェスチャーを使用して 閉じるリクエスト
を送信した際に、Esc keydown
イベントを合成することが含まれます。
event が発火したイベントのうち、もし発火したイベントが複数あれば、どれが選ばれるかは 実装依存です。
event が null でない場合、その キャンセルフラグ が 設定されている場合は、 戻ります。
document が 完全にアクティブ でない場合は 戻ります。
このステップは、もし event が null でない場合、イベントリスナーが document をもはや 完全にアクティブ ではない状態にさせる可能性があるため、必要です。
closedSomething を 閉じるウォッチャーの処理 の結果として設定します document の 関連グローバルオブジェクト で。
closedSomething が true の場合は、戻ります。
代替処理: それ以外の場合は、閉じるリクエスト を監視しているものはありませんでした。ユーザーエージェントは、これを閉じるリクエストとして解釈せず、別のアクションとして解釈するかもしれません。
Esc キーが 閉じるリクエスト
として解釈されるプラットフォームでは、ユーザーエージェントはキーが押された状態を閉じるリクエストとして解釈する必要があります。
したがって、上記のアルゴリズムでは、「関連イベント」として発火するのは単一の keydown
イベントです。
Esc が 閉じるリクエスト
として扱われるプラットフォームでは、ユーザーエージェントは最初に適切に初期化された keydown
イベントを発火させます。もしウェブ開発者が preventDefault()
を呼び出してイベントをキャンセルした場合、何も起こりません。しかし、
イベントがキャンセルされずに発火した場合、ユーザーエージェントは 閉じるウォッチャーの処理 に進みます。
戻るボタンが潜在的な 閉じるリクエスト であるプラットフォームでは、イベントは関与しないため、戻るボタンが押されると、ユーザーエージェントは直接 閉じるウォッチャーの処理 に進みます。 アクティブな 閉じるウォッチャー があれば、それがトリガーされます。そうでない場合、ユーザーエージェントは戻るボタンの押下を別の方法で解釈することができます。例えば、−1 のデルタで履歴を 移動 する要求として解釈することができます。
各 Window には 閉じる監視器マネージャー があり、これは以下の 構造体 で、
次の アイテム を持ちます:
許可されるグループ数、数値で、初期状態では 1 です。
次のユーザーインタラクションで新しいグループを許可する、ブール値で、初期状態では true です。
閉じる監視器マネージャーの複雑さの多くは、ユーザーの歴史遍歴機能を無効にすることを防ぐための反 abuse 保護から来ており、特に 閉じるリクエスト の フォールバックアクション が歴史遍歴の主要なメカニズムであるプラットフォームにおいて重要です。特に:
閉じる監視器のグループ化は、複数の閉じる監視器が 歴史アクションのアクティベーション なしに作成されると、それらがグループ化され、ユーザーがトリガーした 閉じるリクエスト により、グループ内のすべての閉じる監視器が閉じられるように設計されています。これにより、ウェブ開発者は無限の数の閉じるリクエストを傍受することができず、代わりに、最大で 1 + ページのユーザーアクティベーションの回数まで作成できます。
次のユーザーインタラクションは、新しいグループを許可します というブール値は、ウェブ開発者がクローズウォッチャーを個々のユーザーアクティベーションに結びつけて作成することを奨励します。これがなければ、各ユーザーアクティベーションが許可されるグループの数を増加させてしまい、ウェブ開発者がそれらのユーザーアクティベーションを使用してクローズウォッチャーを作成していない場合でも増加してしまいます。簡単に言えば:
許可される: ユーザーインタラクション; 自身のグループに閉じる監視器を作成; ユーザーインタラクション; 2 番目の独立したグループに閉じる監視器を作成。
許可されない: ユーザーインタラクション; ユーザーインタラクション; 自身のグループに閉じる監視器を作成; 2 番目の独立したグループに閉じる監視器を作成。
許可される: ユーザーインタラクション; ユーザーインタラクション; 自身のグループに閉じる監視器を作成; 前のグループとグループ化された閉じる監視器を作成。
この保護は、(1 + ページのユーザーアクティベーションの回数) グループを作成するという目標を守るためには 重要ではありません。悪意のある者は、各ユーザーインタラクションごとに 1 つの閉じる監視器を作成し、将来の悪用のために「蓄積」することができます。しかし、このシステムは通常のケースでより予測可能な動作を生み出し、非悪意のある開発者にユーザーインタラクションに直接応じて閉じる監視器を作成するよう奨励します。
ユーザーアクティベーションについて閉じる監視器マネージャーに通知する ために Window window がある場合:
manager を window の 閉じる監視器マネージャー に設定します。
もし manager の 次のユーザーインタラクションで新しいグループを許可する が true であれば、manager の 許可されるグループ数 を増加させます。
manager の 次のユーザーインタラクションで新しいグループを許可する を false に設定します。
「close watcher」は、次の構造体を持つ項目を持つ構造体です:
「ウィンドウ」、Window。
「キャンセルアクション」、ブール引数を受け取り、ブール値を返すアルゴリズムです。引数は、キャンセルアクションアルゴリズムがアルゴリズムの戻り値によって閉じるリクエストを進めるかどうかを示します。ブール引数が true の場合、アルゴリズムは、呼び出し元が 閉じるアクションに進むことを示す true または呼び出し元が中止することを示す false を返すことができます。引数が false の場合、戻り値は常に false です。このアルゴリズムは例外を投げることはありません。
「閉じるアクション」、引数を取らず、何も返さないアルゴリズムです。このアルゴリズムは例外を投げることはありません。
「キャンセルアクションが実行中」のブール値。
「close watcher」 closeWatcher が closeWatcher の ウィンドウ の close watcher manager 含まれている すべてのリストが 含む ならば、closeWatcher。
close watcher を確立するために、Window window、ステップのリスト cancelAction、およびステップのリスト closeAction が与えられたとき:
確認: window の 関連付けられた Document
が 完全にアクティブ であることを確認します。
closeWatcher を新しい close watcher として設定します。
manager を window の close watcher manager とします。
もし manager の グループ の サイズ が manager の 許可された グループ数 より少ない場合、追加 « closeWatcher » を manager の グループ に追加します。
そうでない場合:
manager の 次のユーザー操作により新しいグループを許可 を true に設定します。
closeWatcher を返します。
閉じる要求をする ために、close watcher closeWatcher:
もし closeWatcher アクティブでない の場合、 true を返します。
もし closeWatcher の キャンセルアクションが実行中 が true の場合、true を返します。
window を closeWatcher の ウィンドウ とします。
もし window の 関連付けられた Document が 完全にアクティブでない の場合、true を返します。
canPreventClose を、window の close watcher manager の グループ の サイズ が window の close watcher manager の 許可されたグループ数 より少ない場合、かつ window が 履歴アクションのアクティベーション を持つ場合には true にし、 それ以外の場合は false にします。
closeWatcher の キャンセルアクションが実行中 を true に設定します。
shouldContinue を、closeWatcher の キャンセルアクション を canPreventClose で実行した結果とします。
closeWatcher の キャンセルアクションが実行中 を false に設定します。
もし shouldContinue が false の場合:
確認: canPreventClose が true であることを確認します。
履歴アクションユーザーアクティベーションの消費 を window に対して行います。
false を返します。
これらのサブステップが 履歴アクションユーザーアクティベーションを消費する ため、close watcher の閉じる要求 を 2 回実行すると、間に ユーザーアクティベーション がないと、2 回目の実行では canPreventClose が false になります。
閉じる closeWatcher を実行します。
true を返します。
閉じる ために、close watcher closeWatcher:
もし closeWatcher アクティブでない の場合、 戻ります。
もし closeWatcher の ウィンドウ の 関連付けられた Document が
完全にアクティブでない の場合、戻ります。
破棄する closeWatcher を実行します。
closeWatcher の 閉じるアクション を実行します。
破棄する ために、close watcher closeWatcher:
manager を closeWatcher の ウィンドウ の close watcher manager とします。
クローズウォッチャーを処理する ために、Window window:
processedACloseWatcher を false に設定します。
もし window の close watcher manager の グループ が空でない場合:
group を window の close watcher manager の グループ の最後の アイテム とします。
各 closeWatcher を group の逆順で:
processedACloseWatcher を true に設定します。
shouldProceed を クローズをリクエストする closeWatcher の結果とします。
もし shouldProceed が false の場合、中断 します。
もし window の close watcher manager の 許可されているグループの数 が 1 より大きい場合、1 減らします。
processedACloseWatcher を返します。
CloseWatcher インターフェイス[Exposed =Window ]
interface CloseWatcher : EventTarget {
constructor (optional CloseWatcherOptions options = {});
undefined requestClose ();
undefined close ();
undefined destroy ();
attribute EventHandler oncancel ;
attribute EventHandler onclose ;
};
dictionary CloseWatcherOptions {
AbortSignal signal ;
};
watcher = new CloseWatcher()
watcher = new CloseWatcher({ signal })
新しい CloseWatcher
インスタンスを作成します。
もし signal
オプションが指定されている場合、watcher は watcher.destroy()
のように、指定された AbortSignal
によって破棄できます。
もし既にアクティブな close watcher があり、かつ
Window
が history-action activation を持たない場合、結果として
CloseWatcher
は、既にアクティブな close watcher
と共に、任意の close request
に応じて閉じられます。(この
既にアクティブな close watcher
は必ずしも CloseWatcher
オブジェクトである必要はありません; モーダルな dialog
要素や、popover
属性を持つ要素によって生成されるポップオーバーである可能性もあります。)
watcher.requestClose()
あたかも close request が
watcher をターゲットに送信されたかのように動作します。まず cancel
イベントを発火させ、もしそのイベントが preventDefault()
でキャンセルされなかった場合は、次に close
イベントを発火させて、watcher.destroy()
が呼ばれたかのように close watcher を非アクティブにします。
これは、cancel と close
イベントハンドラーにキャンセルとクローズのロジックを統合するためのヘルパー ユーティリティです。すべての非 close request クローズの便宜がこのメソッドを呼び出します。
watcher.close()
即座に close イベントを発火させ、その後
watcher.destroy()
が呼ばれたかのように close watcher を非アクティブにします。
これは、close
イベントハンドラー内のクローズ ロジックをトリガーするためのヘルパー ユーティリティです。cancel
イベントハンドラー内のロジックはスキップされます。
watcher.destroy()
watcher を非アクティブにして、もはや close イベントを受け取らず、新しい独立した
CloseWatcher
インスタンスを構築できるようにします。
これは、関連する UI 要素が閉じられる以外の方法で破棄される場合に呼び出されることを意図しています。
各 CloseWatcher
インスタンスには、内部クロースウォッチャー があり、
これは クロースウォッチャー です。
new CloseWatcher(options)
コンストラクタの手順は次のとおりです:
もし this の 関連するグローバルオブジェクト の 関連付けられた
Document が 完全にアクティブ でない場合、「InvalidStateError」
DOMException
をスローします。
closeWatcher を、クロースウォッチャーを確立する の結果として設定します、this の 関連するグローバルオブジェクト を使用して、次の条件で:
cancelAction が
canPreventClose を返すように設定されており、イベントを発火させる
ことが cancel
で this で、cancelable
属性が canPreventClose に初期化されます。
closeAction が、イベントを発火させる
ことが close
で this で行われます。
this の 内部クロースウォッチャー を closeWatcher に設定します。
requestClose() メソッドの手順は、閉じるように要求する
this
の 内部クロースウォッチャー
に対して行います。
close()
メソッドの手順は、閉じる
this
の
内部クロースウォッチャー
に対して行います。
destroy()
メソッドの手順は、破棄する this
の 内部クロースウォッチャー
に対して行います。
以下は、すべての CloseWatcher
インターフェイスを実装するオブジェクトがサポートしなければならない イベントハンドラー
(および対応する イベントハンドラーイベントタイプ)です:
| イベントハンドラー | イベント ハンドラーイベントタイプ |
|---|---|
oncancel
| cancel
|
onclose
| close
|
カスタムピッカーコントロールを実装したい場合、ユーザー提供の
クローズリクエストや
クローズボタンが押されたときに自動的に閉じるようにする方法を示す以下のコードは、
CloseWatcher APIを
使用してクローズリクエストを処理する方法を示しています:
const watcher = new CloseWatcher();
const picker = setUpAndShowPickerDOMElement();
let chosenValue = null ;
watcher. onclose = () => {
chosenValue = picker. querySelector( 'input' ). value;
picker. remove();
};
picker. querySelector( '.close-button' ). onclick = () => watcher. requestClose();
選択された値を収集するロジックが CloseWatcher
オブジェクトの close
イベントハンドラに集約されている点に注目してください。また、クローズボタンの click
イベントハンドラが、そのロジックを委任し requestClose()
を呼び出します。
cancel イベントは、
CloseWatcher
オブジェクトで close
イベントを防ぐために使用でき、CloseWatcher
が破壊されるのを防ぐことができます。典型的な使用例は以下の通りです:
watcher. oncancel = async ( e) => {
if ( hasUnsavedData && e. cancelable) {
e. preventDefault();
const userReallyWantsToClose = await askForConfirmation( "Are you sure you want to close?" );
if ( userReallyWantsToClose) {
hasUnsavedData = false ;
watcher. close();
}
}
};
悪用防止のため、このイベントはページに 履歴アクションのアクティベーション が
なければ キャンセル可能
ではありません。このため、ユーザーが連続して2回クローズリクエストを送信しても、
いずれのリクエストも確実に成功します。2回目のリクエストは cancel
イベントハンドラが preventDefault()
を呼び出そうとする試みを無視し、CloseWatcher を閉じます。
上記の2つの例を組み合わせると、requestClose()
と close()
がどのように異なるかがわかります。クローズボタンの click
イベントハンドラで requestClose()
を使用したため、そのボタンをクリックすると CloseWatcher の
cancel イベントが
トリガーされ、未保存のデータがある場合はユーザーに確認を求めます。もし close()
を使用していた場合、このチェックはスキップされます。場合によってはそれが適切ですが、
通常は requestClose()
の方がユーザーによってトリガーされたクローズリクエストにはより適しています。
ユーザーアクティベーション
制限に加えて、
cancel イベントの
より微妙なユーザーアクティベーションゲーティングがあります。CloseWatcher の
コンストラクションでは、ユーザーアクティベーションなしで複数の CloseWatcher
を作成すると、新しく作成されたものが最近作成された クローズウォッチャー と
グループ化されるため、単一の クローズリクエスト で両方が閉じます:
window. onload = () => {
// これは通常通りに動作します:ユーザーアクティベーションなしで作成された最初のクローズウォッチャーです。
( new CloseWatcher()). onclose = () => {
/* ... */
};
};
button1. onclick = () => {
// これは通常通りに動作します:ボタンクリックがユーザーアクティベーションと見なされます。
( new CloseWatcher()). onclose = () => {
/* ... */
};
button2. onclick = () => {
// これらはグループ化され、単一のクローズリクエストに応じて両方が閉じます。
( new CloseWatcher()). onclose = () => {
/* ... */
};
( new CloseWatcher()). onclose = () => {
/* ... */
};
};
これにより、destroy()、
close()、
または requestClose()
を適切に呼び出すことが重要です。これを行うことで「フリー」なグループ化されていないクローズウォッチャースロットを
取り戻すことができます。このようなユーザーアクティベーションなしで作成されたクローズウォッチャーは、ユーザーの
アクティベーションに応じて生成されないセッションの非アクティブタイムアウトダイアログやサーバーによってトリガーされる
緊急通知などのケースで便利です。
すべての現在のエンジンでサポートされています。
このセクションでは、イベントベースのドラッグアンドドロップメカニズムを定義します。
この仕様では、ドラッグアンドドロップ操作が実際に何であるかは正確には定義されていません。
視覚的なメディアでポインティングデバイスを使用する場合、ドラッグ操作はデフォルトアクションとしてのmousedown
イベントに続いて、一連のmousemove
イベントが続き、ドロップはマウスボタンが解放されることでトリガーされる可能性があります。
ポインティングデバイス以外の入力モダリティを使用する場合、ユーザーはドラッグアンドドロップ操作を実行する意図を明示的に示し、何をドラッグするか、どこにドロップするかをそれぞれ示す必要があるでしょう。
実装方法にかかわらず、ドラッグアンドドロップ操作には開始点(例:マウスがクリックされた場所、またはドラッグのために選択された選択または要素)、任意の数の中間ステップ(ドラッグ中にマウスが移動する要素、またはユーザーが選択肢を循環させる際に選ぶ可能性のあるドロップポイント)、および終了点(マウスボタンが解放された要素、または最終的に選択された要素)またはキャンセルが必要です。終了点は、ドロップが発生する前に最後に選択された可能性のあるドロップポイントでなければなりません(したがって、操作がキャンセルされていない場合は、中間ステップに少なくとも1つの要素が存在する必要があります)。
このセクションは非公式です。
要素をドラッグ可能にするには、その要素に draggable
属性を設定し、dragstart イベントのリスナーを設定して、
ドラッグされているデータを保存します。
イベントハンドラーは通常、ドラッグされているのがテキスト選択でないことを確認する必要があり、
次に、データを DataTransfer オブジェクトに保存し、
許可される効果(コピー、移動、リンク、またはその組み合わせ)を設定する必要があります。
例えば:
< p > あなたはどの果物が好きですか?</ p >
< ol ondragstart = "dragStartHandler(event)" >
< li draggable = "true" data-value = "fruit-apple" > リンゴ</ li >
< li draggable = "true" data-value = "fruit-orange" > オレンジ</ li >
< li draggable = "true" data-value = "fruit-pear" > 梨</ li >
</ ol >
< script >
var internalDNDType = 'text/x-example' ; // この値をあなたのサイトに特有のものに設定します
function dragStartHandler( event) {
if ( event. target instanceof HTMLLIElement) {
// 要素の data-value="" 属性を移動する値として使用します:
event. dataTransfer. setData( internalDNDType, event. target. dataset. value);
event. dataTransfer. effectAllowed = 'move' ; // 移動のみを許可します
} else {
event. preventDefault(); // 選択をドラッグできないようにします
}
}
</ script >
ドロップを受け入れるには、ドロップターゲットが次のイベントをリッスンする必要があります:
dragenter イベント
ハンドラーは、ドロップターゲットがドロップを受け入れる可能性があるかどうかを、イベントをキャンセルすることで報告します。
dragover イベント
ハンドラーは、ユーザーに表示されるフィードバックを指定します。dropEffect
属性を設定して、イベントに関連付けられた DataTransfer
オブジェクトに設定します。
このイベントもキャンセルする必要があります。
drop イベントハンドラーは、
最終的にドロップを受け入れるか拒否する機会があります。ドロップが受け入れられた場合、イベントハンドラーは
ターゲットでドロップ操作を実行する必要があります。このイベントはキャンセルする必要があり、dropEffect
属性の値がソースによって使用されるようにします。そうしないと、ドロップ操作は拒否されます。
例えば:
< p > 好きな果物を下にドロップしてください:</ p >
< ol ondragenter = "dragEnterHandler(event)" ondragover = "dragOverHandler(event)"
ondrop = "dropHandler(event)" >
</ ol >
< script >
var internalDNDType = 'text/x-example' ; // この値をあなたのサイトに特有のものに設定します
function dragEnterHandler( event) {
var items = event. dataTransfer. items;
for ( var i = 0 ; i < items. length; ++ i) {
var item = items[ i];
if ( item. kind == 'string' && item. type == internalDNDType) {
event. preventDefault();
return ;
}
}
}
function dragOverHandler( event) {
event. dataTransfer. dropEffect = 'move' ;
event. preventDefault();
}
function dropHandler( event) {
var li = document. createElement( 'li' );
var data = event. dataTransfer. getData( internalDNDType);
if ( data == 'fruit-apple' )
{
li. textContent = 'リンゴ' ;
}
else if ( data == 'fruit-orange' )
{
li. textContent = 'オレンジ' ;
}
else if ( data == 'fruit-pear' )
{
li. textContent = '梨' ;
}
else {
li. textContent = '不明な果物' ;
}
event. target. appendChild( li);
}
</ script >
元の要素(ドラッグされた要素)を表示から削除するには、dragend
イベントを使用できます。
ここでの例では、元のマークアップを更新してそのイベントを処理する必要があります:
< p > どの果物が好きですか?</ p >
< ol ondragstart = "dragStartHandler(event)" ondragend = "dragEndHandler(event)"
...以前と同じように...
</ ol >
< script >
function dragStartHandler( event) {
// ...以前と同じように...
}
function dragEndHandler( event) {
if ( event. dataTransfer. dropEffect == 'move' )
{
// ドラッグされた要素を削除
event. target. parentNode. removeChild( event. target);
}
}
</ script >
ドラッグ&ドロップ操作の基礎データ、つまり ドラッグデータストア は、以下の情報で構成されています:
ドラッグデータを表す項目のリストである ドラッグデータストア項目リスト。各項目は以下の情報を含みます:
データの種類:
テキスト。
ファイル名を持つバイナリデータ。
データのタイプまたはフォーマットを示す Unicode 文字列で、一般的には MIME タイプ で示されます。一部の値は MIME タイプ ではないものもありますが、レガシーの理由で特別扱いされます。API は MIME タイプ の使用を強制しません。他の値も使用できます。しかし、すべての値は API によって ASCII 小文字に変換されます。
1 つの テキスト 項目は、1 つの 項目タイプ文字列 に限られます。
Unicode またはバイナリ文字列で、場合によってはファイル名(Unicode 文字列)が含まれる、ドラッグデータ項目の種類 に従ったデータ。
ドラッグデータストア項目リスト は、項目がリストに追加された順序で並べられます;最も最近追加された項目が最後になります。
ドラッグ中に UI フィードバックを生成するために使用される以下の情報:
ドラッグデータストアモード は以下のいずれかです:
dragstart
イベント用。新しいデータを ドラッグデータストア
に追加できます。
drop
イベント用。ドラッグされたデータを表す項目のリストを読み取ることができ、データも含まれます。新しいデータを追加することはできません。
その他のすべてのイベント用。ドラッグデータストア内の項目を列挙できますが、データ自体にはアクセスできず、新しいデータを追加することもできません。
ドラッグデータストア許可された効果状態 は、文字列です。
ドラッグデータストア が 作成される ときは、以下のように初期化する必要があります:ドラッグデータストア項目リスト が空であり、ドラッグデータストアデフォルトフィードバック がなく、ドラッグデータストアビットマップ および ドラッグデータストアホットスポット座標 がなく、ドラッグデータストアモード が 保護モード であり、ドラッグデータストア許可された効果状態 が文字列 "uninitialized"
であること。
DataTransfer インターフェース全ての現在のエンジンでサポートされています。
DataTransfer
オブジェクトは、ドラッグ&ドロップ操作の基礎となる ドラッグデータストア
を公開するために使用されます。
[Exposed =Window ]
interface DataTransfer {
constructor ();
attribute DOMString dropEffect ;
attribute DOMString effectAllowed ;
[SameObject ] readonly attribute DataTransferItemList items ;
undefined setDragImage (Element image , long x , long y );
/* old interface */
readonly attribute FrozenArray <DOMString > types ;
DOMString getData (DOMString format );
undefined setData (DOMString format , DOMString data );
undefined clearData (optional DOMString format );
[SameObject ] readonly attribute FileList files ;
};
dataTransfer = new DataTransfer()
全ての現在のエンジンでサポートされています。
新しい DataTransfer
オブジェクトを作成し、空の ドラッグデータストア
を持ちます。
dataTransfer.dropEffect [ = value ]
全ての現在のエンジンでサポートされています。
現在選択されている操作の種類を返します。操作の種類が effectAllowed
属性で許可されているものでない場合、操作は失敗します。
選択された操作を変更するために設定できます。
dataTransfer.effectAllowed [ = value ]
全ての現在のエンジンでサポートされています。
許可される操作の種類を返します。
(dragstart
イベント中に)設定でき、許可される操作を変更できます。
可能な値は "none"、
"copy"、
"copyLink"、
"copyMove"、
"link"、
"linkMove"、
"move"、
"all"、
および "uninitialized"
です。
dataTransfer.items
全ての現在のエンジンでサポートされています。
DataTransferItemList
オブジェクトを返し、ドラッグデータを含みます。
dataTransfer.setDragImage(element, x, y)
全ての現在のエンジンでサポートされています。
指定した要素を使用してドラッグフィードバックを更新し、以前に指定されたフィードバックを置き換えます。
dataTransfer.types
全ての現在のエンジンでサポートされています。
フローズン
配列 を返し、dragstart
イベントで設定されたフォーマットをリストします。さらに、ファイルがドラッグされている場合は、タイプの1つが "Files" になります。
data = dataTransfer.getData(format)
全ての現在のエンジンでサポートされています。
指定されたデータを返します。データが存在しない場合は、空の文字列を返します。
dataTransfer.setData(format, data)
全ての現在のエンジンでサポートされています。
指定されたデータを追加します。
dataTransfer.clearData([ format ])
全ての現在のエンジンでサポートされています。
指定されたフォーマットのデータを削除します。引数が省略された場合は、すべてのデータが削除されます。
dataTransfer.files
全ての現在のエンジンでサポートされています。
ドラッグされているファイルの FileList
を返します。ファイルがない場合は空です。
DataTransfer オブジェクトは、ドラッグアンドドロップイベント の一部として作成されるもので、これらのイベントが発火している間のみ有効です。
DataTransfer
オブジェクトは、その有効な間、ドラッグデータストア
に関連付けられています。
DataTransfer オブジェクトには、関連付けられた
types 配列 があり、これは FrozenArray<DOMString>
で、初期状態では空です。DataTransfer
オブジェクトの ドラッグデータストアアイテムリスト が変更された場合、または DataTransfer オブジェクトが ドラッグデータストア
との関連付けが解除された場合、次の手順を実行します。
L を空のシーケンスとして設定します。
もし DataTransfer
オブジェクトがまだ ドラッグデータストア
に関連付けられている場合は、次のようにします:
DataTransfer
オブジェクトの ドラッグデータストアアイテムリスト の各アイテムで、その
kind
が text であるものについて、アイテムの type string からのエントリを
L に追加します。
もし DataTransfer
オブジェクトの ドラッグデータストアアイテムリスト に、kind が File
であるアイテムがある場合、"Files" という文字列のエントリを L
に追加します。(この値は他の値と区別できます。なぜなら、他の値は小文字であるからです。)
DataTransfer オブジェクトの
types
配列 を、L から フローズン配列 を作成する結果に設定します。
DataTransfer()
コンストラクタが呼び出されると、新しく作成された DataTransfer
オブジェクトが次のように初期化されます。
ドラッグデータストア の アイテムリスト を空のリストに設定します。
ドラッグデータストア の モード を 読み書きモード に設定します。
dropEffect
と
effectAllowed
を "none" に設定します。
dropEffect 属性は、ドラッグアンドドロップ操作中にユーザーに与えられるフィードバックを制御します。DataTransfer
オブジェクトが作成されると、dropEffect
属性は文字列値に設定されます。取得時には現在の値を返す必要があります。設定時には、新しい値が "none"、"copy"、"link"、または "move"
のいずれかであれば、属性の現在の値は新しい値に設定されなければなりません。他の値は無視されなければなりません。
effectAllowed 属性は、ドラッグアンドドロップ処理モデルで dropEffect
属性を dragenter
および
dragover
イベント中に初期化するために使用されます。DataTransfer
オブジェクトが作成されると、effectAllowed
属性は文字列値に設定されます。取得時には現在の値を返す必要があります。設定時には、ドラッグデータストア の モード が 読み書きモード であり、新しい値が "none"、"copy"、"copyLink"、"copyMove"、"link"、"linkMove"、"move"、"all"、または "uninitialized"
のいずれかであれば、属性の現在の値は新しい値に設定されなければなりません。それ以外の場合は、変更されることなくそのままにされなければなりません。
items
属性は、DataTransferItemList
オブジェクトを返さなければなりません。このオブジェクトは DataTransfer
オブジェクトに関連付けられています。
setDragImage(image, x, y)
メソッドは次の手順を実行しなければなりません:
DataTransfer
オブジェクトがもはや ドラッグデータストア
に関連付けられていない場合、処理を終了します。何も起こりません。
ドラッグデータストア の モード が 読み書きモード でない場合、処理を終了します。何も起こりません。
image が img
要素である場合、その要素の画像を (その 自然サイズ で) ドラッグデータストアビットマップ
に設定します。そうでない場合は、指定された要素から生成された画像を ドラッグデータストアビットマップ に設定します
(この方法の詳細は現在指定されていません)。
ドラッグデータストアホットスポット座標 を指定された x、y 座標に設定します。
types 属性は、この
DataTransfer オブジェクトの types array
を返さなければなりません。
getData(format) メソッドは次の手順を実行しなければなりません:
DataTransfer
オブジェクトがもはや ドラッグデータストア
に関連付けられていない場合、空文字列を返します。
ドラッグデータストア の モード が 保護モード である場合、空文字列を返します。
format を最初の引数として、ASCII小文字に変換 します。
convert-to-URL を false に設定します。
format が "text" の場合、"text/plain" に変更します。
format が "url" の場合、"text/uri-list" に変更し、convert-to-URL を
true に設定します。
ドラッグデータストアアイテムリスト に、kind が text で、type string が format に等しいアイテムがない場合、空文字列を返します。
result を ドラッグデータストアアイテムリスト で、kind が Plain Unicode string で、type string が format に等しいアイテムのデータに設定します。
convert-to-URL が true の場合、result を text/uri-list
データに適切にパースし、その後、リストから最初の URL を設定します (存在する場合)。存在しない場合は空文字列にします。 [RFC2483]
result を返します。
setData(format, data) メソッドは次の手順を実行しなければなりません:
DataTransfer
オブジェクトがもはや ドラッグデータストア
に関連付けられていない場合、処理を終了します。何も起こりません。
ドラッグデータストア の モード が 読み書きモード でない場合、処理を終了します。何も起こりません。
format を最初の引数として、ASCII小文字に変換 します。
format が "text" の場合、"text/plain" に変更します。
format が "url" の場合、"text/uri-list" に変更します。
ドラッグデータストアアイテムリスト から、kind が text で、type string が format に等しいアイテムを削除します (存在する場合)。
ドラッグデータストアアイテムリスト に、kind が text で、type string が format に等しく、データがメソッドの第二引数で与えられた文字列であるアイテムを追加します。
clearData(format) メソッドは次の手順を実行しなければなりません:
DataTransfer
オブジェクトがもはや ドラッグデータストア
に関連付けられていない場合、処理を終了します。何も起こりません。
ドラッグデータストア の モード が 読み書きモード でない場合、処理を終了します。何も起こりません。
もしメソッドが引数なしで呼び出された場合、ドラッグデータストアアイテムリスト から、kind が Plain Unicode string であるアイテムを削除し、処理を終了します。
format を format に設定し、ASCII小文字に変換 します。
format が "text" の場合、"text/plain" に変更します。
format が "url" の場合、"text/uri-list" に変更します。
ドラッグデータストアアイテムリスト から、kind が text で、type string が format に等しいアイテムを削除します (存在する場合)。
clearData()
メソッドは、ドラッグにファイルが含まれていたかどうかには影響しません。したがって、types
属性のリストは、clearData()
を呼び出した後でも空でない可能性があります(ドラッグにファイルが含まれていた場合、リストには "Files" という文字列が含まれるままです)。
files
属性は、次の手順によって見つかったファイルを表す ライブ FileList
シーケンスを返さなければなりません。さらに、指定された FileList
オブジェクトと指定された基になるファイルについて、同じ File
オブジェクトを毎回使用しなければなりません。
空のリスト L で始めます。
DataTransfer
オブジェクトがもはや ドラッグデータストア
に関連付けられていない場合、FileList
は空です。空のリスト L を返します。
ドラッグデータストア の モード が 保護モード の場合、空のリスト L を返します。
ドラッグデータストアアイテムリスト の中で、kind が File であるアイテムについて、そのデータ(ファイル、特にその名前と内容、および type)をリスト L に追加します。
これらの手順によって見つかったファイルは、リスト L に含まれるものです。
このバージョンのAPIは、ドラッグ中にファイルの種類を公開しません。
DataTransferItemList
インターフェースすべての現在のエンジンでサポートされています。
各DataTransferオブジェクトは、DataTransferItemListオブジェクトに関連付けられています。
[Exposed=Window]
interface DataTransferItemList {
readonly attribute unsigned long length;
getter DataTransferItem (unsigned long index);
DataTransferItem? add(DOMString data, DOMString type);
DataTransferItem? add(File data);
undefined remove(unsigned long index);
undefined clear();
};
items.length
すべての現在のエンジンでサポートされています。
ドラッグデータストア内のアイテムの数を返します。
items[index]
ドラッグデータストア内のindex番目のエントリを表すDataTransferItemオブジェクトを返します。
items.remove(index)
すべての現在のエンジンでサポートされています。
ドラッグデータストア内のindex番目のエントリを削除します。
items.clear()
すべての現在のエンジンでサポートされています。
ドラッグデータストア内のすべてのエントリを削除します。
items.add(data)
すべての現在のエンジンでサポートされています。
items.add(data, type)
指定されたデータに対して新しいエントリをドラッグデータストアに追加します。データがプレーンテキストの場合は、type文字列も指定する必要があります。
DataTransferItemListオブジェクトのDataTransferオブジェクトがドラッグデータストアに関連付けられている場合、DataTransferItemListオブジェクトのモードは、ドラッグデータストアモードと同じです。DataTransferItemListオブジェクトのDataTransferオブジェクトがドラッグデータストアに関連付けられていない場合、DataTransferItemListオブジェクトのモードは無効モードです。このセクションで参照されているドラッグデータストア(これは、DataTransferItemListオブジェクトが無効モードでない場合にのみ使用されます)は、DataTransferItemListオブジェクトのDataTransferオブジェクトに関連付けられているドラッグデータストアです。
length属性は、オブジェクトが無効モードの場合はゼロを返さなければなりません。それ以外の場合は、ドラッグデータストアアイテムリスト内のアイテム数を返さなければなりません。
DataTransferItemListオブジェクトが無効モードでない場合、そのサポートされているプロパティインデックスは、インデックスです。ドラッグデータストアアイテムリストの。
インデックス付きプロパティの値を決定するために、DataTransferItemListオブジェクトのiについて、ユーザーエージェントはDataTransferItemオブジェクトを返さなければなりません。これは、i番目のアイテムを表します。ドラッグデータストア。特定のアイテムがこのDataTransferItemListオブジェクトから取得されるたびに、同じオブジェクトが返されなければなりません。DataTransferItemオブジェクトは、最初に作成されたときにDataTransferオブジェクトと同じDataTransferItemListオブジェクトに関連付けられていなければなりません。
add()メソッドは、次の手順を実行する必要があります:
もしDataTransferItemListオブジェクトが読み取り/書き込みモードでない場合、nullを返します。
次のリストから適切な手順セットにジャンプします:
すでにテキストの種類を持ち、メソッドの第2引数の値に等しい型文字列を持つアイテムがドラッグデータストアアイテムリストにすでに存在する場合、ASCII小文字に変換されて、"NotSupportedError" DOMExceptionをスローします。
それ以外の場合は、ドラッグデータストアアイテムリストに、メソッドの第2引数の値に等しい型文字列を持ち、ASCII小文字に変換され、メソッドの第1引数で与えられた文字列をデータとするアイテムを追加します。
Fileである場合
ドラッグデータストアアイテムリストに、Fileの種類を持ち、型がFileと同じで、ASCII小文字に変換されたアイテムを追加します。
新しく追加されたアイテムに対応するインデックス付きプロパティの値を決定し、その値(新しく作成されたDataTransferItemオブジェクト)を返します。
remove(index)メソッドは次の手順を実行する必要があります:
もしDataTransferItemListオブジェクトが読み取り/書き込みモードでない場合、"InvalidStateError" DOMExceptionをスローします。
ドラッグデータストアにindex番目のアイテムが含まれていない場合、何もせずに終了します。
ドラッグデータストアからindex番目のアイテムを削除します。
clear()メソッドは、DataTransferItemListオブジェクトが読み取り/書き込みモードである場合、ドラッグデータストアからすべてのアイテムを削除しなければなりません。それ以外の場合は、何もしてはなりません。
DataTransferItem
インターフェースすべての現在のエンジンでサポートされています。
各DataTransferItemオブジェクトは、DataTransferオブジェクトに関連付けられています。
[Exposed=Window]
interface DataTransferItem {
readonly attribute DOMString kind;
readonly attribute DOMString type;
undefined getAsString(FunctionStringCallback? _callback);
File? getAsFile();
};
callback FunctionStringCallback = undefined (DOMString data);
item.kind
すべての現在のエンジンでサポートされています。
ドラッグデータアイテムの種類を返します。次のいずれかです: "string", "file"。
item.type
すべての現在のエンジンでサポートされています。
ドラッグデータアイテム型文字列を返します。
item.getAsString(callback)
すべての現在のエンジンでサポートされています。
コールバックを、ドラッグデータアイテムの種類がテキストである場合に、文字列データを引数として呼び出します。
file = item.getAsFile()
すべての現在のエンジンでサポートされています。
ドラッグデータアイテムの種類がFileである場合、Fileオブジェクトを返します。
次の条件に該当する場合、DataTransferItemオブジェクトのモードは、ドラッグデータストアモードと同じです。DataTransferオブジェクトがドラッグデータストアに関連付けられており、そのドラッグデータストアアイテムリストに、DataTransferItemオブジェクトが表すアイテムがまだ含まれている場合です。DataTransferItemオブジェクトのDataTransferオブジェクトがドラッグデータストアに関連付けられていない場合、またはDataTransferItemオブジェクトが表すアイテムが該当するドラッグデータストアアイテムリストから削除された場合、DataTransferItemオブジェクトのモードは無効モードとなります。このセクションで参照されているドラッグデータストア(これはDataTransferItemオブジェクトが無効モードでない場合にのみ使用されます)は、DataTransferItemオブジェクトのDataTransferオブジェクトに関連付けられているドラッグデータストアです。
kind
属性は、DataTransferItem
オブジェクトが無効モードにある場合、空文字列を返さなければなりません。それ以外の場合は、次の表の第1列のセルにドラッグデータアイテムの種類が含まれる行の第2列のセルに記載されている文字列を返さなければなりません。オブジェクトが表す項目のDataTransferItemに基づきます。
| 種類 | 文字列 |
|---|---|
| テキスト | "string"
|
| ファイル | "file"
|
type属性は、DataTransferItemオブジェクトが無効モードである場合は空文字列を返さなければなりません。それ以外の場合は、DataTransferItemオブジェクトが表すアイテムのドラッグデータアイテム型文字列を返さなければなりません。
getAsString(callback)メソッドは、次の手順を実行する必要があります。
callbackがnullである場合、終了します。
DataTransferItemオブジェクトが読み取り/書き込みモードまたは読み取り専用モードでない場合、終了します。この場合、コールバックは実行されません。
ドラッグデータアイテムの種類がテキストでない場合、終了します。この場合も、コールバックは実行されません。
それ以外の場合は、タスクをキューに追加し、DataTransferItemオブジェクトが表すアイテムの実際のデータを引数としてコールバックを実行します。
getAsFile()メソッドは、次の手順を実行する必要があります。
DataTransferItemオブジェクトが読み取り/書き込みモードまたは読み取り専用モードでない場合、nullを返します。
ドラッグデータアイテムの種類がファイルでない場合、nullを返します。
新しいFileオブジェクトを返し、DataTransferItemオブジェクトが表すアイテムの実際のデータを表します。
DragEventインターフェースすべての現在のエンジンでサポートされています。
すべての現在のエンジンでサポートされています。
ドラッグアンドドロップの処理モデルには、いくつかのイベントが含まれます。それらはすべて、DragEventインターフェースを使用します。
[Exposed =Window ]
interface DragEvent : MouseEvent {
constructor (DOMString type , optional DragEventInit eventInitDict = {});
readonly attribute DataTransfer ? dataTransfer ;
};
dictionary DragEventInit : MouseEventInit {
DataTransfer ? dataTransfer = null ;
};
event.dataTransfer
すべての現在のエンジンでサポートされています。
イベントのDataTransferオブジェクトを返します。
他のイベントインターフェースとの一貫性のために、DragEventインターフェースにはコンストラクターがありますが、特に役立つものではありません。特に、スクリプトから有用なDataTransferオブジェクトを作成する方法はありません。なぜなら、DataTransferオブジェクトは、ドラッグアンドドロップ中にブラウザによって調整される処理およびセキュリティモデルを持っているからです。
DragEventインターフェースのdataTransfer属性は、初期化された値を返す必要があります。それはイベントのコンテキスト情報を表します。
ユーザーエージェントが特定のeという名前のDNDイベントを発火し、特定のドラッグデータストアを使用し、必要に応じて特定の関連ターゲットと共に要素に対して行う必要がある場合、ユーザーエージェントは次の手順を実行する必要があります:
特定の関連ターゲットが提供されていない場合、関連ターゲットをnullに設定します。
windowを、指定されたターゲット要素のDocumentオブジェクトの関連するグローバルオブジェクトに設定します。
eがdragstartの場合、ドラッグデータストアモードを読み取り/書き込みモードに設定し、dataDragStoreWasChangedをtrueに設定します。
eがドロップの場合、ドラッグデータストアモードを読み取り専用モードに設定します。
与えられたドラッグデータストアに関連する新しいDataTransferオブジェクトを作成します。
effectAllowed属性を、ドラッグデータストアのドラッグデータストア許可効果状態に設定します。
eがdragstart、ドラッグ、またはドラッグリーブの場合、dropEffect属性を"なし"に設定します。それ以外の場合は、次の表に示されているように、effectAllowed属性の値とドラッグアンドドロップのソースに基づいて値を設定します(すなわち、eがdragenterまたはdragoverの場合)。
effectAllowed
|
dropEffect
|
|---|---|
"なし"
|
"なし"
|
"コピー"
|
"コピー"
|
"コピーリンク"
|
"コピー",
または、適切な場合に"リンク"
|
"コピー移動"
|
"コピー",
または、適切な場合に"移動"
|
"すべて"
|
"コピー",
または、適切な場合に"リンク"または"移動"
|
"リンク"
|
"リンク"
|
"リンク移動"
|
"リンク",
または、適切な場合に"移動"
|
"移動"
|
"移動"
|
"未初期化"(テキストコントロールから選択されたものをドラッグする場合)
|
"移動",
または、適切な場合に"コピー"または"リンク"
|
"未初期化"(選択されたものをドラッグする場合)
|
"コピー",
または、適切な場合に"リンク"または"移動"
|
"未初期化"(a要素をドラッグし、href属性がある場合)
|
"リンク",
または、適切な場合に"コピー"または"移動"
|
| その他のケース | "コピー",
または、適切な場合に"リンク"または"移動"
|
上記の表に可能な適切な代替案が提供されている場合、ユーザーエージェントは、プラットフォームの規約に従い、ユーザーがこれらの代替効果を要求した場合に、リストされている代替値を使用することができます。
たとえば、Windowsプラットフォームの規約では、「alt」キーを押しながらドラッグすると、データのリンクを移動やコピーよりも優先して示すことになります。そのため、Windowsシステムでは、上記の表に基づいて「リンク」がオプションであり、「alt」キーが押されている場合、ユーザーエージェントは「コピー」または「移動」の代わりにこれを選択することができます。
eventのtype属性をeに、bubbles属性をtrueに、view属性をwindowに、relatedTarget属性を関連ターゲットに設定し、dataTransfer属性をdataTransferに設定します。
eがdragleaveまたはdragendでない場合、eventのcancelable属性をtrueに設定します。
eventのマウスおよびキーの属性を、ユーザーインタラクションイベントに対する入力デバイスの状態に従って初期化します。
関連するポインティングデバイスがない場合、eventのscreenX、screenY、clientX、clientY、およびbutton属性を0に初期化します。
ドラッグデータストア許可効果状態をdataTransferのeffectAllowed属性の現在の値に設定します。(これは、eがdragstartの場合にのみ値を変更することができます。)
dataDragStoreWasChangedがtrueの場合、ドラッグデータストアモードを保護モードに戻します。
dataTransferとドラッグデータストアの関連を解除します。
ユーザーがドラッグ操作を開始しようとした場合、ユーザーエージェントは以下の手順を実行しなければなりません。 ドラッグが他のドキュメントやアプリケーションで開始され、ユーザーエージェントがそのドラッグが発生していることに気づかなかった場合でも、ユーザーエージェントはこれらの手順が実行されたかのように振る舞わなければなりません。
次のようにして、ドラッグされているものを決定します:
ドラッグ操作が選択範囲に対して起動された場合、ドラッグされているのは選択範囲です。
それ以外の場合、ドラッグ操作がDocumentに対して起動された場合、ユーザーがドラッグしようとしたノードから始まり、上位の要素まで登っていく最初の要素が
IDL属性draggable
が true に設定されているかどうかを確認します。もしそのような要素がなければ、何もドラッグされていません。ドラッグアンドドロップ操作は開始されません。
それ以外の場合、ドラッグ操作はユーザーエージェントの管理範囲外で起動されました。ドラッグされているものは、ドラッグが開始されたドキュメントやアプリケーションで定義されます。
img
要素およびa
要素でhref
属性を持つものは、デフォルトでdraggable
属性が true に設定されています。
ドラッグデータストアを作成します。以降の手順で発生するすべてのDNDイベントは、このドラッグデータストアを使用しなければなりません。
ソースノードとなるDOMノードを確定します:
ドラッグされているのが選択範囲の場合、ソースノードは、ユーザーがドラッグを開始したText
ノードです(通常は、ユーザーが最初にクリックしたText
ノード)。ユーザーが特定のノードを指定しなかった場合、例えば「選択範囲をドラッグする」とユーザーが指定した場合、ソースノードは、選択範囲の一部を含む最初のText
ノードです。
それ以外の場合、ドラッグされているのが要素の場合、ソースノードは ドラッグされている要素です。
それ以外の場合、ソースノードは 他のドキュメントやアプリケーションの一部です。この場合、イベントをソースノードで発生させる必要がある場合、ユーザーエージェントはその状況に関連するプラットフォーム固有の慣習に従わなければなりません。
ドラッグアンドドロップ操作の過程でソースノードに対して複数のイベントが発生します。
ドラッグされたノードのリストを次のように決定します:
ドラッグされているのが選択範囲の場合、ドラッグされたノードのリスト には、ツリー順 で選択範囲に部分的または完全に含まれるすべてのノード(その祖先も含む)が含まれます。
それ以外の場合、 ドラッグされたノードのリストには ソースノードのみが含まれます。
ドラッグされているのが選択範囲の場合、 ドラッグデータストアアイテムリストにアイテムを追加し、そのプロパティを次のように設定します:
text/plain"
それ以外の場合、ファイルがドラッグされている場合は、 ドラッグデータストアアイテムリストにファイルごとに1つのアイテムを追加し、そのプロパティを次のように設定します:
application/octet-stream"
(それ以外の場合)。
ファイルをドラッグすることは、現在、ナビゲーブル外でのみ行うことができます。 例: ファイルシステムマネージャーアプリケーションなどから。
ドラッグがアプリケーション外で開始された場合、ユーザーエージェントは、ドラッグされているデータに適したアイテムを ドラッグデータストアアイテムリストに追加し、適切な場合はプラットフォームの慣習に従います。ただし、プラットフォームの慣習がドラッグされたデータをラベル付けするためにMIMEタイプを使用しない場合、ユーザーエージェントは、MIMEタイプにマッピングするために最善の努力をしなければならず、いずれの場合も、ドラッグデータアイテムタイプ文字列はすべて、ASCII小文字に変換する必要があります。
ユーザーエージェントは、選択範囲またはドラッグされた要素を他の形式、例: HTML などで表現するアイテムを1つ以上追加することもできます。
ドラッグされたノードのリストが空でない場合は、それらのノードからマイクロデータをJSON形式に抽出し、そのプロパティを次のように設定してドラッグデータストアアイテムリストにアイテムを1つ追加します:
application/microdata+json
次のサブステップを実行します:
urls を「」とします。
ドラッグされたノードのリスト内の各nodeに対して以下を行います:
a
要素で、href
属性を持つ場合
href
内容属性の値を基に、その要素のノードドキュメントに対して相対的に行います。
img
要素で、src
属性を持つ場合
src
内容属性の値を基に、その要素のノードドキュメントに対して相対的に行います。
urls が空のままである場合、終了します。
url string をurls内の文字列を結合した結果とし、それらを追加された順にU+000DキャリッジリターンU+000Aラインフィード文字の組み合わせ(CRLF)で区切ります。
次のプロパティで ドラッグデータストアアイテムリストにアイテムを1つ追加します:
text/uri-list
ユーザーエージェントに適した方法でドラッグデータストアデフォルトフィードバックを更新します (ユーザーが選択範囲をドラッグしている場合は、その選択範囲がこのフィードバックの基礎となる可能性があり、要素をドラッグしている場合は、その要素のレンダリングが使用されます。ドラッグがユーザーエージェント外で開始された場合は、ドラッグフィードバックを決定するためのプラットフォームの慣習が使用されるべきです)。
DNDイベントを発生させる。イベント名は
dragstart
で、ソースノードで発生させます。
イベントがキャンセルされた場合、ドラッグアンドドロップ操作は行われません。終了します。
イベントリスナーが登録されていないイベントは、ほとんど定義上キャンセルされることがないため、著者が特に防止しない限り、ユーザーに対してドラッグアンドドロップが常に利用可能です。
ポインターイベントを発生させる。ソースノードでpointercancelという名前で発生させ、
Pointer Eventsにより必要な他のフォローアップイベントも発生させます。[POINTEREVENTS]
プラットフォームの慣習に従い、以下に記述されているように、ドラッグアンドドロップ操作を開始します。
ドラッグアンドドロップのフィードバックは、以下の最初の利用可能なソースから生成されなければなりません:
ユーザーエージェントがドラッグアンドドロップ操作を開始する瞬間から、ドラッグアンドドロップ操作の終了まで、デバイス入力イベント(例:マウスやキーボードのイベント)は抑制されなければなりません。
ドラッグ操作中、ユーザーがドロップターゲットとして直接指示した要素は即時ユーザー選択と呼ばれます(ユーザーは要素しか選択できません。他の ノードはドロップターゲットとして利用可能にしてはいけません)。しかし、即時ユーザー選択が必ずしも現在のターゲット要素であるとは限りません。 それは、ドラッグアンドドロップ操作のドロップ部分に現在選択されている要素です。
即時ユーザー選択は、ユーザーが異なる要素を選択するにつれて (ポインティングデバイスで指したり、他の方法で選択したりすることで)変わります。現在のターゲット要素は、以下に説明されているように、ドキュメント内のイベントリスナーの結果に基づいて、即時ユーザー選択 が変わると変化します。
現在のターゲット要素と即時ユーザー選択の両方が null である可能性があり、これはターゲット要素が選択されていないことを意味します。両方が他の(DOMベースの)ドキュメントや、全く別の(ウェブではない)プログラムの要素である可能性もあります(例: ユーザーがテキストをワードプロセッサにドラッグする場合)。現在のターゲット要素は初めはnullです。
また、現在のドラッグ操作があり、これは
"none", "copy", "link", および "move" の値を取ることができます。最初は、"none"
の値を持ちます。
それは、以下の手順で説明されているように、ユーザーエージェントによって更新されます。
ユーザーエージェントは、ドラッグ操作が 開始されるとすぐに、そしてドラッグ操作が続いている限り、毎回350ms(±200ms)後にタスクをキューに追加して 次の手順を順に実行しなければなりません。
ユーザーエージェントが前回のシーケンスのイテレーションを実行している間に次のイテレーションが発生した場合、このイテレーションをスキップして戻ります(実質的にはドラッグ&ドロップ操作の「フレームを飛ばす」)。
ドラッグ&ドロップイベントを発火し、名前はドラッグ、ソースノードで発火します。このイベントがキャンセルされた場合、ユーザーエージェントは現在のドラッグ操作を「なし」(ドラッグ操作なし)に設定しなければなりません。
イベントがキャンセルされず、ユーザーがドラッグ&ドロップ操作を終了していない場合、次のようにドラッグ&ドロップ操作の状態を確認します。
ユーザーが前回のイテレーション(または最初のイテレーションの場合)と異なる即時ユーザー選択を示している場合、そしてこの即時ユーザー選択が現在のターゲット要素と同じでない場合、次のようにして現在のターゲット要素を更新します。
現在のターゲット要素もnullに設定します。
現在のターゲット要素を即時ユーザー選択に設定します。
ドラッグ&ドロップイベントを発火し、名前はドラッグエンター、即時ユーザー選択で発火します。
イベントがキャンセルされた場合、現在のターゲット要素を即時ユーザー選択に設定します。
それ以外の場合、次のリストから適切なステップを実行します。
textareaや、input要素であり、type属性がテキスト状態にあるもの)、編集ホストまたは編集可能要素であり、ドラッグデータストアアイテムリストにドラッグデータアイテムタイプ文字列
"text/plain"
と ドラッグデータアイテム種別
テキストを含むアイテムがある場合
現在のターゲット要素を即時ユーザー選択に設定します。
現在のターゲット要素は変更しません。
ドラッグ&ドロップイベントを発火し、名前はドラッグエンター、body要素(存在する場合)またはDocumentオブジェクト(存在しない場合)で発火します。その後、イベントがキャンセルされたかどうかに関わらず、現在のターゲット要素をbody要素に設定します。
前のステップで現在のターゲット要素が変更され、前のターゲット要素がnullでないか非DOMドキュメントの一部であった場合、ドラッグ&ドロップイベントを発火し、名前はドラッグリーブ、新しい現在のターゲット要素を特定の関連ターゲットとして、前のターゲット要素で発火します。
もし現在のターゲット要素がDOM要素である場合、ドラッグ&ドロップイベントを発火し、名前はドラッグオーバー、この現在のターゲット要素で発火します。
もしドラッグオーバーイベントがキャンセルされていない場合、次のリストから適切なステップを実行します。
textarea、またはinput要素であり、type属性がテキスト状態にあるもの)、編集ホストまたは編集可能要素であり、ドラッグデータストアアイテムリストにドラッグデータアイテムタイプ文字列
"text/plain"
と ドラッグデータアイテム種別
テキストを含むアイテムがある場合
それ以外の場合(dragover
イベントがキャンセルされた場合)、以下の表に従って、イベントのディスパッチが完了した後のDragEventオブジェクトのdataTransferオブジェクトのeffectAllowed属性とdropEffect属性の値に基づいて、現在のドラッグ操作を設定します。
effectAllowed
| dropEffect
| ドラッグ操作 |
|---|---|---|
"未初期化","コピー","コピーリンク","コピー移動","すべて"
| "コピー"
| "コピー"
|
"未初期化","リンク","コピーリンク","リンク移動","すべて"
| "リンク"
| "リンク"
|
"未初期化","移動","コピー移動","リンク移動","すべて"
| "移動"
| "移動"
|
| その他のケース | "なし"
| |
それ以外の場合、現在のターゲット要素がDOM要素でない場合、プラットフォーム固有のメカニズムを使用して、実行されているドラッグ操作(なし、コピー、リンク、または移動)を判断し、現在のドラッグ操作を適切に設定します。
ドラッグのフィードバック(例:マウスカーソル)を現在のドラッグ操作に一致させるように更新します。
| ドラッグ操作 | フィードバック |
|---|---|
"コピー"
| ここにドロップするとデータがコピーされます。 |
"リンク"
| ここにドロップするとデータがリンクされます。 |
"移動"
| ここにドロップするとデータが移動されます。 |
"なし"
| 操作は許可されておらず、ここにドロップするとドラッグ&ドロップ操作がキャンセルされます。 |
それ以外の場合、ユーザーがドラッグアンドドロップ操作を終了した場合(例:マウス操作のドラッグアンドドロップインターフェースでマウスボタンを放した場合)、またはdragイベントがキャンセルされた場合、これが最後のイテレーションになります。次の手順を実行し、ドラッグアンドドロップ操作を停止します:
現在のドラッグ操作が「none」(ドラッグ操作なし)である場合、またはユーザーがドラッグアンドドロップ操作をキャンセルして終了した場合(例:Escapeキーを押した場合)、または現在のターゲット要素がnullである場合、ドラッグ操作は失敗しました。次のサブステップを実行します:
droppedをfalseに設定します。
現在のターゲット要素がDOM要素である場合、DNDイベント「dragleave」をその要素で発火させます。それ以外の場合は、nullでなければ、ドラッグキャンセルのためにプラットフォーム固有の規約を使用します。
それ以外の場合、ドラッグ操作が成功する可能性があります。次のサブステップを実行します:
droppedをtrueに設定します。
現在のターゲット要素がDOM要素である場合、DNDイベント「drop」をその要素で発火させます。それ以外の場合は、ドロップを示すためにプラットフォーム固有の規約を使用します。
イベントがキャンセルされた場合、イベントのディスパッチが完了した後のDragEventオブジェクトのdataTransferオブジェクトのdropEffect属性の値に現在のドラッグ操作を設定します。
それ以外の場合、イベントはキャンセルされません。次のように、正確なターゲットに応じてイベントのデフォルトアクションを実行します:
textarea、またはinput要素で、type属性がText状態にあるもの)または編集ホストまたは編集可能な要素であり、ドラッグデータストアアイテムリストに「text/plain」というドラッグデータアイテムタイプ文字列を持つアイテムが含まれている場合
ドラッグデータストアアイテムリストの最初のアイテムの実際のデータを、編集ホストまたは編集可能な要素に、プラットフォーム固有の規約(例:現在のマウスカーソル位置に挿入、またはフィールドの末尾に挿入)に従って挿入します。
イベント「dragend」のデフォルトアクションとして、次のリストから適切な手順を実行します:
move」であり、ドラッグアンドドロップ操作のソースが編集ホスト内に完全に含まれているDOM内の選択である場合
move」であり、ドラッグアンドドロップ操作のソースがテキストコントロール内の選択である場合
ユーザーエージェントは、該当するテキストコントロールからドラッグされた選択を削除する必要があります。
none」である場合
ドラッグはキャンセルされました。プラットフォームの規約によりこれがユーザーに対して表現される場合(例:ドラッグされた選択がドラッグアンドドロップ操作のソースに戻るアニメーションが表示される場合)、そのようにします。
イベントにはデフォルトのアクションがありません。
このステップの目的で、テキストコントロールとは、textarea要素またはinput要素であり、そのtype属性がText、Search、Tel、URL、Email、Password、またはNumber状態にあるものを指します。
ユーザーエージェントは、スクロール可能な領域の端付近でドラッグが発生した場合にどのように反応するかを検討することが推奨されます。例えば、ユーザーが長いページの下部にリンクをドラッグした場合、ページをスクロールして、ユーザーがそのリンクをページの下部にドロップできるようにすることが理にかなっているかもしれません。
このモデルは、関与するノードがどのDocumentオブジェクトから来たかに依存しません。イベントは上記の通りに発火し、処理モデルの残りも、操作に関与するドキュメントの数に関係なく、上記の通りに実行されます。
このセクションは規範的ではありません。
以下のイベントは、ドラッグアンドドロップモデルに関連しています。
| イベント名 | ターゲット | キャンセル可能か? | ドラッグデータストアモード | dropEffect
| デフォルトアクション |
|---|---|---|---|---|---|
dragstart
すべての現在のエンジンでサポートされています。 Firefox9+Safari3.1+Chrome1+
Opera12+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android12+ | ソースノード | ✓ キャンセル可能 | 読み書きモード | "none"
| ドラッグアンドドロップ操作の開始 |
drag
すべての現在のエンジンでサポートされています。 Firefox9+Safari3.1+Chrome1+
Opera12+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android12+ | ソースノード | ✓ キャンセル可能 | 保護モード | "none"
| ドラッグアンドドロップ操作の継続 |
dragenter
すべての現在のエンジンでサポートされています。 Firefox9+Safari3.1+Chrome1+
Opera12+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android12+ | 即時ユーザー選択 またはbody 要素 | ✓ キャンセル可能 | 保護モード | effectAllowed 値に基づく
| 即時ユーザー選択 をターゲット要素として拒否する |
dragleave
すべての現在のエンジンでサポートされています。 Firefox9+Safari3.1+Chrome1+
Opera12+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android12+ | 前のターゲット要素 | — | 保護モード | "none"
| なし |
dragover
すべての現在のエンジンでサポートされています。 Firefox9+Safari3.1+Chrome1+
Opera12+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android12+ | 現在のターゲット要素 | ✓ キャンセル可能 | 保護モード | effectAllowed 値に基づく
| 現在のドラッグ操作を"none"にリセット |
drop
すべての現在のエンジンでサポートされています。 Firefox9+Safari3.1+Chrome1+
Opera12+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android12+ | 現在のターゲット要素 | ✓ キャンセル可能 | 読み取り専用モード | 現在のドラッグ操作 | 様々 |
dragend
すべての現在のエンジンでサポートされています。 Firefox9+Safari3.1+Chrome1+
Opera12+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android12+ | ソースノード | — | 保護モード | 現在のドラッグ操作 | 様々 |
これらすべてのイベントはバブルし、構成され、effectAllowed属性は、dragstartイベント後の値を常に持ち、デフォルトは未初期化です。
draggable
属性すべての現在のエンジンでサポートされています。
すべてのHTML 要素には、draggableコンテンツ属性を設定できます。draggable属性は、次のキーワードと状態を持つ列挙型属性です:
| キーワード | 状態 | 簡単な説明 |
|---|---|---|
true
| true | 要素はドラッグ可能です。 |
false
| false | 要素はドラッグできません。 |
属性の欠落値のデフォルトおよび無効値のデフォルトはどちらもauto状態です。auto状態はユーザーエージェントのデフォルトの動作を使用します。
draggable属性を持つ要素には、非視覚的な操作を目的として、要素の名前を示すtitle属性も持つべきです。
element.draggable [ = value ]
要素がドラッグ可能な場合は true を返します。それ以外の場合は false を返します。
デフォルトを上書きしてdraggableコンテンツ属性を設定することができます。
draggableIDL属性は、その値が以下で説明する方法でコンテンツ属性に依存しており、要素がドラッグ可能かどうかを制御します。一般的に、テキスト選択のみがドラッグ可能ですが、draggableIDL属性が true
の要素もドラッグ可能になります。
要素のdraggableコンテンツ属性が状態trueを持つ場合、draggableIDL属性はtrueを返さなければなりません。
それ以外の場合、要素のdraggableコンテンツ属性が状態falseを持つ場合、draggableIDL属性はfalseを返さなければなりません。
それ以外の場合、要素のdraggableコンテンツ属性が状態autoを持つ場合、要素がimg要素、画像を表すobject要素、またはa要素であり、hrefコンテンツ属性を持つ場合、draggableIDL属性はtrueを返さなければなりません。それ以外の場合、draggableIDL属性はfalseを返さなければなりません。
draggableIDL属性がfalseに設定されている場合、draggableコンテンツ属性はリテラル値
"false" に設定されなければなりません。draggableIDL属性がtrueに設定されている場合、draggableコンテンツ属性はリテラル値
"true" に設定されなければなりません。
ユーザーエージェントは、DataTransferオブジェクトにdragstartイベント中に追加されたデータを、dropイベントまでスクリプトに利用可能にしてはなりません。さもないと、ユーザーが機密情報をあるドキュメントから別のドキュメントにドラッグする際、途中で敵対的な第三のドキュメントを通過すると、その敵対的なドキュメントがデータを傍受する可能性があるからです。
同じ理由から、ユーザーエージェントはユーザーが明示的にドラッグ操作を終了した場合にのみドロップを成功と見なすべきです。スクリプトがドラッグ操作を終了した場合は、ドロップは失敗(キャンセル)と見なされ、dropイベントは発生してはなりません。
ユーザーエージェントは、スクリプトのアクションに応じてドラッグアンドドロップ操作を開始しないよう注意する必要があります。たとえば、マウスとウィンドウの環境で、スクリプトがユーザーがマウスボタンを押している間にウィンドウを移動させた場合、UAはそれをドラッグの開始とは見なしません。これは、そうしないとUAが機密ソースからデータを敵対的なドキュメントにユーザーの同意なしにドラッグさせる可能性があるため、重要です。
ユーザーエージェントは、ドラッグおよびドロップ時に、潜在的にアクティブな(スクリプト化された)コンテンツ(例:HTML)を、既知の安全な機能の安全リストを使用してフィルタリングする必要があります。同様に、相対URLは、予期しない方法で参照が変更されるのを避けるために、絶対URLに変換されるべきです。本仕様は、これがどのように行われるかを指定していません。
敵対的なページがコンテンツを提供し、ユーザーにそのコンテンツを選択してドラッグアンドドロップ(または実際にコピーアンドペースト)させ、被害者ページのcontenteditable領域に移動させることを考えてみてください。ブラウザが安全なコンテンツのみがドラッグされることを保証しない場合、選択範囲内のスクリプトやイベントハンドラなどの潜在的に安全でないコンテンツが被害者サイトにドロップ(またはペースト)されると、被害者サイトの権限を取得します。これにより、クロスサイトスクリプティング攻撃が可能になります。
popover属性すべての現在のエンジンでサポートされています。
すべてのHTML要素にはpopoverコンテンツ属性を設定できます。指定された場合、要素は表示されるまでレンダリングされず、その時点で他のページコンテンツの上にレンダリングされます。
popover属性は、著者が最も関連するセマンティクスを持つ要素にポップオーバー機能を適用できるようにするグローバル属性です。
次の例は、ウェブサイトのグローバルナビゲーション内にポップオーバーサブナビゲーションリンクのリストを作成する方法を示しています。
< ul >
< li >
< a href = ... > All Products</ a >
< button popovertarget = sub-nav >
< img src = down-arrow.png alt = "Product pages" >
</ button >
< ul popover id = sub-nav >
< li >< a href = ... > Shirts</ a >
< li >< a href = ... > Shoes</ a >
< li >< a href = ... > Hats etc.</ a >
</ ul >
</ li >
<!-- 他のリストアイテムやリンクがここにあります -->
</ ul >
popoverをアクセシビリティのセマンティクスを持たない要素、例えばdiv要素に使用する場合、著者はポップオーバーがアクセス可能であることを確保するために適切なARIA属性を使用する必要があります。
次の例は、カスタムメニューポップオーバーを作成するための基本的なマークアップを示しています。ポップオーバーが起動されると、autofocus属性の使用により最初のメニュー項目がキーボードフォーカスを受け取ります。矢印キーによるメニュー項目のナビゲーションとアクティベーション動作は、引き続き著者のスクリプトが必要です。カスタムメニューウィジェットを構築するための追加の要件は、WAI-ARIA仕様に定義されています。
< button popovertarget = m > Actions</ button >
< div role = menu id = m popover >
< button role = menuitem tabindex = -1 autofocus > Edit</ button >
< button role = menuitem tabindex = -1 > Hide</ button >
< button role = menuitem tabindex = -1 > Delete</ button >
</ div >
ポップオーバーは、ユーザーが実行したアクションを確認するためにステータスメッセージを表示するのに便利です。次の例は、output要素でポップオーバーを表示する方法を示しています。
< button id = submit > Submit</ button >
< p >< output >< span popover = manual ></ span ></ output ></ p >
< script >
const sBtn = document. getElementById( "submit" );
const outSpan = document. querySelector( "output [popover=manual]" );
let successMessage;
let errorMessage;
/* アクションの成功を判定するロジックと、使用する適切な成功またはエラーメッセージを定義する */
sBtn. addEventListener( "click" , ()=> {
if ( success ) {
outSpan. textContent = successMessage;
}
else {
outSpan. textContent = errorMessage;
}
outSpan. showPopover();
setTimeout( function () {
outSpan. hidePopover();
}, 10000 );
});
</ script >
output要素にポップオーバー要素を挿入すると、一般的にそのコンテンツが表示されるときにスクリーンリーダーがそれをアナウンスします。コンテンツの複雑さや頻度によっては、これがこれらの支援技術のユーザーにとって有用であるか、煩わしいかもしれません。output要素やその他のARIAライブリージョンを使用する際には、最良のユーザー体験を確保するためにこの点に留意してください。
popover属性は、次のキーワードと状態を持つ列挙型属性です。
| キーワード | 状態 | 簡単な説明 |
|---|---|---|
auto
| auto | 開いたときに他のポップオーバーを閉じます。ライトディスミスを持ち、閉じるリクエストに応答します。 |
| (空文字列) | ||
manual
| manual | 他のポップオーバーを閉じません。ライトディスミスや閉じるリクエストには応答しません。 |
属性の欠落値のデフォルトはポップオーバーなし状態であり、無効値のデフォルトはmanual状態です。
すべての現在のエンジンでサポートされています。
popoverIDL属性は、反映され、popover属性を持ち、既知の値に限定されます。
すべてのHTML要素には、ポップオーバー表示状態があり、初期状態はです。状態の値は以下の通りです:
非表示
表示中
Documentには、ポップオーバーのポインターダウンターゲットがあり、それはHTML要素またはnullで、初期状態はnullです。
すべてのHTML要素には、ポップオーバー呼び出し元があり、それはHTML要素またはnullで、初期状態はnullです。
すべてのHTML要素には、ポップオーバー表示または非表示があり、それはブール値で、初期状態はfalseです。
すべてのHTML要素には、ポップオーバー切り替えタスクトラッカーがあり、それは切り替えタスクトラッカーまたはnullで、初期状態はnullです。
すべてのHTML要素には、ポップオーバー閉じるウォッチャーがあり、それは閉じるウォッチャーまたはnullで、初期状態はnullです。
次の属性変更ステップは、element、localName、oldValue、value、およびnamespaceが与えられた場合に、すべてのHTML要素に使用されます:
namespaceがnullでない場合、戻ります。
localNameがpopoverでない場合、戻ります。
elementのポップオーバー表示状態が表示中の状態にあり、oldValueとvalueが異なる状態にある場合、element、true、true、およびfalseが与えられたポップオーバー非表示アルゴリズムを実行します。
element.showPopover()popover属性がauto状態にある場合、auto状態の他のポップオーバーをすべて閉じます。ただし、それらがelementの最上位ポップオーバー祖先アルゴリズムによって祖先とみなされる場合を除きます。element.hidePopover()display: noneを適用することでポップオーバーを非表示にします。element.togglePopover()
すべての現在のエンジンでサポートされています。
showPopover()メソッドの手順は、ポップオーバーを表示を実行し、this、true、およびnullを与えられます。
ポップオーバーを表示するには、指定されたHTML要素の element、booleanのthrowExceptions、およびHTML要素またはnullのinvokerを使用します。
element、false、throwExceptions、およびnullを指定してポップオーバーの有効性を確認を実行し、その結果がfalseであれば、処理を終了します。
documentをelementのノードドキュメントとして設定します。
確認: elementのポップオーバー呼び出し元がnullであることを確認します。
nestedShowをelementのポップオーバー表示または非表示状態として設定します。
elementのポップオーバー表示または非表示状態をtrueに設定します。
次のステップをcleanupShowingFlagとして設定します:
もしnestedShowがfalseであれば、elementのポップオーバー表示または非表示状態をfalseに設定します。
次のイベントを発火させた結果がfalseであれば、cleanupShowingFlagを実行し、終了します。
ポップオーバーの有効性を確認を再度実行し、結果がfalseであればcleanupShowingFlagを実行して終了します。
ポップオーバーの有効性確認は、beforetoggleイベントの発火によってこの要素が切断されたり、popover属性が変更されたりした可能性があるため、再度実行されます。
shouldRestoreFocusをfalseに設定します。
もしelementのpopover属性がauto状態にある場合:
originalTypeをelementのpopover属性の値として設定します。
ancestorをelement、invoker、およびtrueを指定して最上位のポップオーバー祖先アルゴリズムを実行した結果として設定します。
もしancestorがnullであれば、ancestorをdocumentに設定します。
ancestor、false、およびnestedShowではない値を指定してすべてのポップオーバーを非表示にするを実行します。
もしoriginalTypeがelementのpopover属性の値と等しくない場合:
もしthrowExceptionsがtrueであれば、"InvalidStateError" DOMExceptionをスローします。
処理を終了します。
ポップオーバーの有効性を確認を再度実行し、結果がfalseであればcleanupShowingFlagを実行して終了します。
ポップオーバーの有効性確認は、上記のすべてのポップオーバーを非表示にするを実行した結果、beforetoggleイベントが発火し、そのイベントハンドラがこの要素を切断したり、popover属性を変更したりした可能性があるため、再度実行されます。
もしdocumentに対して最上位の自動ポップオーバーを実行した結果がnullであれば、shouldRestoreFocusをtrueに設定します。
これは、スタック内の最初のポップオーバーに対してのみ、以前にフォーカスされていた要素にフォーカスを戻すことを保証します。
elementのポップオーバーの閉じるウォッチャーを、elementの関連するグローバルオブジェクトを指定して閉じるウォッチャーの確立を実行した結果に設定します。その際に:
キャンセルアクションがtrueを返すように設定します。
閉じるアクションが、elementに対してtrue、true、およびfalseを指定してポップオーバーを非表示にするを実行するように設定します。
elementの以前にフォーカスされた要素をnullに設定します。
originallyFocusedElementをdocumentのドキュメントのフォーカスエリアのDOMアンカーとして設定します。
最上層に要素を追加するをelementを指定して実行します。
elementのポップオーバーの可視状態を表示中に設定します。
elementのポップオーバー呼び出し元をinvokerに設定します。
elementを指定してポップオーバーのフォーカス手順を実行します。
もしshouldRestoreFocusがtrueであり、elementのpopover属性がno
popover状態にない場合、elementの以前にフォーカスされた要素をoriginallyFocusedElementに設定します。
ポップオーバートグルイベントタスクをキューに追加するをelement、"closed"、および"open"を指定して実行します。
cleanupShowingFlagを実行します。
ポップオーバートグルイベントタスクをキューに追加するには、要素element、文字列oldState、および文字列newStateを指定して実行します:
もしelementのポップオーバートグルタスクトラッカーがnullでない場合、次の処理を行います:
oldStateをelementのポップオーバートグルタスクトラッカーの以前の状態に設定します。
elementのポップオーバートグルタスクトラッカーのタスクをタスクキューから削除します。
elementのポップオーバートグルタスクトラッカーをnullに設定します。
要素タスクをキューに追加し、DOM操作タスクソースとelementを指定して、以下のステップを実行します:
イベントを発火させ、elementでtoggleイベントを、ToggleEventを使用して、oldState属性にoldStateを、newState属性にnewStateを設定します。
elementのポップオーバートグルタスクトラッカーをnullに設定します。
elementのポップオーバートグルタスクトラッカーを、直前にキューに追加されたタスクを含む構造体に設定し、タスクを設定し、以前の状態をoldStateに設定します。
Support in all current engines.
The hidePopover()メソッドの手順は次のとおりです:
ポップオーバー非表示アルゴリズムを実行し、this、true、true、およびtrueを指定します。
ポップオーバーを非表示にするためには、指定されたHTML要素 element、booleanの focusPreviousElement、booleanのfireEvents、およびbooleanの throwExceptionsを使用して次の手順を実行します。
element、true、throwExceptions、およびnullを指定してポップオーバーの有効性を確認を実行し、その結果がfalseであれば、処理を終了します。
documentをelementのノードドキュメントとして設定します。
nestedHideをelementのポップオーバーの表示または非表示状態として設定します。
elementのポップオーバーの表示または非表示状態をtrueに設定します。
もしnestedHideがtrueであれば、fireEventsをfalseに設定します。
cleanupStepsを以下の手順として設定します。
もしnestedHideがfalseであれば、elementのポップオーバーの表示または非表示状態をfalseに設定します。
もしelementのポップオーバーの閉じるウォッチャーがnullでない場合、次の処理を行います。
破棄 elementのポップオーバーの閉じるウォッチャー
elementのポップオーバーの閉じるウォッチャーをnullに設定します。
もしelementのポップオーバー属性が
自動状態にある場合、次の処理を行います。
element、focusPreviousElement、およびfireEventsを指定してすべてのポップオーバーを非表示にするを実行します。
element、true、throwExceptionsを指定してポップオーバーの有効性を確認を再度実行し、その結果がfalseであればcleanupStepsを実行して処理を終了します。
ポップオーバーの有効性確認は、すべてのポップオーバーを非表示にするを実行することで
elementが切断されたり、ポップオーバー属性が変更されたりした可能性があるため、再度実行されます。
autoPopoverListContainsElementをdocumentの 表示中の自動ポップオーバーリストの最後の項目がelementである場合はtrue、そうでない場合はfalseに設定します。
elementのポップオーバー呼び出し元をnullに設定します。
もしfireEventsがtrueであれば:
イベントを発火させ、
elementでbeforetoggleイベントを、
ToggleEventを使用して、
oldState属性を"open"に、
newState属性を"closed"に設定します。
autoPopoverListContainsElementがtrueであり、かつdocumentの 表示中の自動ポップオーバーリストの最後の項目がelementでない場合は、 element、focusPreviousElement、およびfalseを指定してすべてのポップオーバーを非表示にするを実行します。
element、true、throwExceptions、およびnullを指定してポップオーバーの有効性を確認を再度実行し、その結果がfalseであればcleanupStepsを実行して処理を終了します。
ポップオーバーの有効性確認は、
beforetoggleイベントの発火により
elementが切断されたり、ポップオーバー属性が変更されたりした可能性があるため、再度実行されます。
そうでない場合、elementを指定して直ちに最上層から要素を削除するを実行します。
elementのポップオーバーの可視状態を に設定します。
もしfireEventsがtrueであれば、element、"open"、および"closed"を指定してポップオーバートグルイベントタスクをキューに追加するを実行します。
previouslyFocusedElementをelementの以前にフォーカスされた要素として設定します。
もしpreviouslyFocusedElementがnullでない場合:
elementの以前にフォーカスされた要素をnullに設定します。
もしfocusPreviousElementがtrueであり、かつdocumentのドキュメントのフォーカスエリアの DOMアンカーがelementの シャドウを含む包括的子孫である場合、previouslyFocusedElementの フォーカス手順を実行します。このステップを実行してもビューポートはスクロールされないようにします。
cleanupStepsを実行します。
すべての現行エンジンでサポートされています。
togglePopover(force)
メソッドの手順は次のとおりです。
もしthisのポップオーバーの可視状態が 表示中であり、 forceが指定されていないかfalseの場合は、 ポップオーバー非表示アルゴリズムを this、true、true、 およびtrueを指定して実行します。
それ以外の場合、forceが指定されていないかtrueであれば、 ポップオーバーを表示を this、true、およびnullを指定して実行します。
それ以外の場合:
もしthisの ポップオーバーの可視状態が 表示中であれば expectedToBeShowingをtrue、そうでなければfalseに設定します。
expectedToBeShowing、true、およびnullを指定してポップオーバーの有効性を確認を実行します。
thisの ポップオーバーの可視状態が 表示中であればtrueを、そうでなければfalseを返します。
指定された要素に到達するまで、すべてのポップオーバーを非表示にしますには、HTML要素またはDocument
endpoint、booleanの
focusPreviousElement、およびbooleanのfireEventsを指定して実行します。
もしendpointがHTML要素であり、 endpointがポップオーバー表示中状態にない場合は、処理を終了します。
documentをendpointのノードドキュメントとして設定します。
closeAllOpenPopoversアルゴリズムを次の手順として設定します。
popoverをdocumentの最上位の自動ポップオーバーとして設定します。
popoverがnullでない間:
popover、focusPreviousElement、fireEvents、およびfalseを指定してポップオーバーを非表示にするを実行します。
popoverをdocumentの最上位の自動ポップオーバーとして再設定します。
もしendpointがDocumentである場合は、closeAllOpenPopoversを実行し、処理を終了します。
repeatingHideをfalseに設定します。
次の手順を少なくとも1回実行します:
lastToHideをnullに設定します。
foundEndpointをfalseに設定します。
次の処理をdocumentの表示中の自動ポップオーバーリスト内の各popoverに対して行います。
もしpopoverがendpointである場合、foundEndpointをtrueに設定します。
それ以外の場合、foundEndpointがtrueであればlastToHideをpopoverに設定し、ループを終了します。
もしfoundEndpointがfalseであれば、closeAllOpenPopoversを実行し、処理を終了します。
lastToHideがnullでなく、lastToHideのポップオーバーの可視状態が表示中であり、 documentの表示中の自動ポップオーバーリストが空でない場合:
documentの表示中の自動ポップオーバーリストの最後の要素を指定して、focusPreviousElement、fireEvents、およびfalseを指定してポップオーバーを非表示にするを実行します。
もしdocumentの表示中の自動ポップオーバーリストがendpointを含み、 かつdocumentの表示中の自動ポップオーバーリストの最後の要素がendpointでない場合、repeatingHideをtrueに設定します。それ以外の場合はfalseに設定します。
もしrepeatingHideがtrueであれば、fireEventsをfalseに設定します。
そして、repeatingHideがtrueである限り、これらの手順を繰り返し実行します。
指定された要素に到達するまで、すべてのポップオーバーを非表示にしますアルゴリズムは、 何かが発生したときに開いたままにしないポップオーバーを非表示にするためにいくつかのケースで使用されます。例えば、ポップオーバーのライトディスマス中に、このアルゴリズムはユーザーがクリックしたノードと関係のないポップオーバーのみを閉じることを保証します。
最上位のポップオーバーの先祖を見つけるには、
ノード
newPopoverOrTopLayerElement、HTML要素または
nullのinvoker、およびbooleanのisPopoverを指定して次の手順を実行します。これらはHTML要素またはnullを返します。
最上位のポップオーバーの先祖アルゴリズムは、 指定されたポップオーバーまたは最上層の要素に対して、 表示中の自動ポップオーバーリスト内で 最も上位にある(最新の)先祖ポップオーバーを返します。ポップオーバーは複数の方法で互いに関連し、 ポップオーバーのツリーを作成します。1つのポップオーバー(「子」と呼ぶ)が最上位の先祖ポップオーバー(「親」と呼ぶ)を持つパスは2つあります。
ポップオーバーがノードツリー内で互いにネストされている場合。この場合、子孫ポップオーバーが「子」であり、 その最上位の先祖ポップオーバーが「親」となります。
呼び出し要素(例: ボタン)が
ポップオーバーを指すpopovertarget属性を持っている場合。
この場合、ポップオーバーが「子」であり、呼び出し要素が含まれるポップオーバーのサブツリーが「親」となります。
呼び出し元はポップオーバー内にあり、開いているポップオーバーを参照している必要があります。
上記の各関係において、親ポップオーバーは子ポップオーバーよりも 表示中の自動ポップオーバーリスト内で厳密に早くなければならず、 そうでない場合は有効な先祖関係を形成しません。これにより、非表示のポップオーバーや自己参照(例: ポップオーバーに含まれる呼び出し要素が 再度そのポップオーバーを指す場合)を排除し、 サイクルグラフからよく形成されたツリーを構築することができます。 自動のポップオーバーのみが考慮されます。
提供された要素がポップオーバーとして表示されていない
ダイアログなどの最上層要素である場合、
最上位のポップオーバーの先祖は
最初のポップオーバーを見つけるためにのみノードツリー内を検索します。
isPopoverがtrueの場合:
確認: newPopoverOrTopLayerElementの
ポップオーバー属性が、
ポップオーバーなしの状態や
手動状態ではないこと。
確認: newPopoverOrTopLayerElementの ポップオーバーの可視状態が、 表示中の状態ではないこと。
それ以外の場合:
確認: invokerがnullであること。
popoverPositionsを空の順序付きマップとして設定します。
indexを0に設定します。
documentをnewPopoverOrTopLayerElementのノードドキュメントとして設定します。
documentの表示中の自動ポップオーバーリスト内の各popoverについて:
設定 popoverPositions[popover]にindexを設定します。
indexを1増やします。
isPopoverがtrueの場合、設定 popoverPositions[newPopoverOrTopLayerElement]にindexを設定します。
indexを1増やします。
topmostPopoverAncestorをnullに設定します。
checkAncestorを次の手順を実行するアルゴリズムとして設定します:
candidateがnullの場合は、処理を終了します。
candidateAncestorをcandidateを指定して最も近い包括的な開いているポップオーバーとして設定します。
candidateAncestorがnullの場合は、処理を終了します。
candidatePositionをpopoverPositions[candidateAncestor]として設定します。
もしtopmostPopoverAncestorがnullであるか、popoverPositions[topmostPopoverAncestor]が candidatePositionよりも小さい場合は、topmostPopoverAncestorをcandidateAncestorに設定します。
newPopoverOrTopLayerElementの親ノードを指定してcheckAncestorを実行します。この親ノードはフラットツリー内に存在します。
invokerを指定してcheckAncestorを実行します。
topmostPopoverAncestorを返します。
与えられたノードnodeに対して、最も近い包括的な開いているポップオーバーを見つけるために、次の手順を実行します。これらの手順はHTML要素またはnullを返します。
currentNodeをnodeとして設定します。
currentNodeがnullでない限り:
currentNodeのポップオーバー属性が自動状態であり、currentNodeのポップオーバーの可視状態が表示中である場合、currentNodeを返します。
currentNodeをフラットツリー内のcurrentNodeの親ノードに設定します。
nullを返します。
与えられたドキュメントdocumentに対して、最上位の自動ポップオーバーを見つけるために、次の手順を実行します。これらの手順はHTML要素またはnullを返します。
documentの表示中の自動ポップオーバーリストが空でない場合は、documentの表示中の自動ポップオーバーリストの最後の要素を返します。
nullを返します。
subjectとして指定されたHTML要素に対して、ポップオーバーのフォーカス手順を実行します:
もしsubjectがダイアログ要素である場合、subjectに対してダイアログフォーカス手順を実行し、終了します。
もしsubjectがオートフォーカス属性を持っている場合、controlをsubjectとします。
それ以外の場合、controlをsubjectに対するオートフォーカスデリゲートに設定します。
もしcontrolがnullである場合、終了します。
フォーカス手順をcontrolに対して実行します。
topDocumentをcontrolのアクティブドキュメントとして設定します。これはcontrolのノードドキュメントのブラウジングコンテキストのトップレベルブラウジングコンテキストです。
空にする topDocumentのオートフォーカス候補を。
topDocumentのオートフォーカス処理済みフラグをtrueに設定します。
与えられたHTML要素elementに対して、ポップオーバーの有効性を確認するために、ブール値のexpectedToBeShowing、throwExceptions、およびドキュメントまたはnullのexpectedDocumentを与えて、次の手順を実行します。これらの手順は、例外をスローするか、ブール値を返します。
elementのポップオーバー属性がポップオーバーなしの状態である場合:
throwExceptionsがtrueである場合、"NotSupportedError" DOMExceptionをスローします。
falseを返します。
次のいずれかが真である場合:
expectedToBeShowingがtrueであり、elementのポップオーバーの可視状態が表示中でない場合。
expectedToBeShowingがfalseであり、elementのポップオーバーの可視状態がでない場合。
その場合、falseを返します。
次のいずれかが真である場合:
elementが接続されていない場合。
expectedDocumentがnullでなく、elementのノードドキュメントがexpectedDocumentでない場合。
elementのフルスクリーンフラグが設定されている場合。
その場合:
throwExceptionsがtrueである場合、"InvalidStateError" DOMExceptionをスローします。
falseを返します。
trueを返します。
与えられたDocumentdocumentに対して、表示中の自動ポップオーバーリストを取得するために:
popoversを« »に設定します。
各要素elementに対して、documentのトップレイヤーにある場合: もしelementのポップオーバー属性が自動状態にあり、かつelementのポップオーバー可視状態が表示中である場合、そのelementをpopoversに追加します。
popoversを返します。
ボタンには、次のコンテンツ属性があります:
popovertarget
popovertargetaction
指定された場合、popovertarget属性の値は、同じツリー内で、ポップオーバー属性を持つ要素のIDでなければなりません。
popovertargetaction属性は、次のキーワードと状態を持つ列挙型属性です:
| キーワード | 状態 | 簡潔な説明 |
|---|---|---|
toggle
| toggle | ターゲットとなるポップオーバー要素を表示または非表示にします。 |
show
| show | ターゲットとなるポップオーバー要素を表示します。 |
hide
| hide | ターゲットとなるポップオーバー要素を非表示にします。 |
この属性の省略時の値と無効な値のデフォルトは、どちらもtoggle状態です。
可能な限り、ポップオーバー要素をDOM内でトリガーとなる要素の直後に配置することをお勧めします。これにより、スクリーンリーダーなどの支援技術を使用するユーザーに対して、論理的なプログラム読み取り順序でポップオーバーが公開されるのを確実にするのに役立ちます。
popovertarget属性とpopovertargetaction属性を組み合わせて、ポップオーバーを表示および閉じる方法を次に示します:
< button popovertarget = "foo" popovertargetaction = "show" > ポップオーバーを表示</ button >
< article popover = "auto" id = "foo" > これはポップオーバーの記事です!< button popovertarget = "foo" popovertargetaction = "hide" > 閉じる</ button > </ article >
もしpopovertargetaction属性が指定されていない場合、デフォルトのアクションは関連するポップオーバーをトグルすることになります。次に示すのは、手動ポップオーバーを開閉状態にトグルするために、呼び出しボタンにpopovertarget属性だけを指定する方法です。手動ポップオーバーは、ライトディスミスや閉じるリクエストに反応しません:
< input type = "button" popovertarget = "foo" value = "ポップオーバーをトグル" >
< div popover = manual id = "foo" > これはポップオーバーです!</ div >
インターフェイス mixin PopoverInvokerElement {
[CEReactions ] 属性 Element ? popoverTargetElement ;
[CEReactions ] 属性 DOMString popoverTargetAction ;
};
HTMLButtonElement/popoverTargetElement
全ての現行エンジンでサポートされています。
HTMLInputElement/popoverTargetElement
全ての現行エンジンでサポートされています。
popoverTargetElementIDL属性は、popovertarget属性を反映する必要があります。
HTMLButtonElement/popoverTargetAction
全ての現行エンジンでサポートされています。
HTMLInputElement/popoverTargetAction
全ての現行エンジンでサポートされています。
popoverTargetActionIDL属性は、popovertargetaction属性を反映する必要があります。
ポップオーバーターゲット属性のアクティベーション動作をNode
nodeに対して実行するには:
popoverをnodeのポップオーバーターゲット要素とする。
popoverがnullの場合、終了する。
nodeのpopovertargetaction属性が表示状態で、popoverのポップオーバー可視性状態が表示の場合、終了する。
nodeのpopovertargetaction属性が非表示状態で、popoverのポップオーバー可視性状態がの場合、終了する。
popoverのポップオーバー可視性状態が表示の場合、ポップオーバー非表示アルゴリズムをpopover、true、true、およびfalseを与えて実行する。
それ以外の場合、popoverのポップオーバー可視性状態がであり、ポップオーバーの有効性をチェックをpopover、false、false、nullを与えて実行した結果がtrueの場合、ポップオーバーを表示をpopover、false、およびnodeを与えて実行する。
ポップオーバーターゲット要素をNode
nodeに対して取得するには、次の手順を実行する。それはHTML要素またはnullを返す。
nodeがボタンでない場合、nullを返す。
nodeが無効化されている場合、nullを返す。
popoverElementをnodeのpopovertarget関連要素を取得の実行結果とする。
popoverElementがnullの場合、nullを返す。
popoverElementを返す。
「ライトディスミス」とは、popover属性が
auto状態にあるポップオーバーの外側をクリックすると、そのポップオーバーが閉じられることを意味します。これは、
クローズリクエストに対する反応に加えて行われます。
次の手順に従って、開いているポップオーバーをライトディスミスすることができます。引数としてイベント
eventが与えられます。
targetをeventのターゲットとします。
documentをtargetのノードドキュメントとします。
topmostPopoverを、最も上にある自動ポップオーバー をdocumentに対して実行した結果とします。
topmostPopoverがnullの場合、終了します。
eventがポインターイベント
であり、eventのタイプが「ポインターダウン」である場合、次を実行します:
documentのポップオーバーポインターダウンターゲットを、targetを引数として
最も上にあるクリックされたポップオーバー
を実行した結果に設定します。
eventがポインターイベント
であり、eventのタイプが「ポインターアップ」である場合:
ancestorを、targetを引数として最も上にあるクリックされたポップオーバーを実行した結果とします。
sameTargetを、ancestorがdocumentのポップオーバーポインターダウンターゲットである場合にtrueとします。
documentのポップオーバーポインターダウンターゲットをnullに設定します。
ancestorがnullの場合、ancestorをdocumentに設定します。
sameTargetがtrueである場合、ancestor、false、およびtrueを引数としてすべてのポップオーバーを非表示にするまでを実行します。
開いているポップオーバーのライトディスミスは、ポインターイベント仕様によって、ユーザーがページ上でクリックまたはタッチしたときに呼び出されます。
最も上にあるクリックされたポップオーバーを、次の手順に従ってノード
nodeを引数として取得します。
clickedPopoverをnodeを引数として最も近い包括的な開いているポップオーバーを実行した結果とします。
invokerPopoverをnodeを引数としてインボーカー用の最も近い包括的なターゲットポップオーバーを実行した結果とします。
getStackPositionを次の手順に従って実行するアルゴリズムとします。引数としてHTML要素 popoverが与えられます:
popoverListをpopoverのノードドキュメントの 表示されている自動ポップオーバーリストとします。
popoverがpopoverListに含まれている場合、popoverList内のpopoverのインデックス+1を返します。
0を返します。
もし、getStackPositionをclickedPopoverに対して実行した結果が、invokerPopoverに対して実行した結果より大きい場合、clickedPopoverを返します。
invokerPopoverを返します。
インボーカー用の最も近い包括的なターゲットポップオーバーを、次の手順に従って取得します。引数としてノード
nodeが与えられます。
currentNodeをnodeとします。
currentNodeがnullでない間、次を実行します:
targetPopoverをcurrentNodeのポップオーバーターゲット要素とします。
targetPopoverがnullでなく、targetPopoverのpopover属性がauto状態にあり、targetPopoverのポップオーバー可視性状態が表示である場合、targetPopoverを返します。
currentNodeをcurrentNodeのフラットツリー内の祖先に設定します。
このセクションでは、主にウェブブラウザーに直接適用される機能について説明します。ただし、特に指定がない限り、このセクションで定義された要件は、ウェブブラウザーに限らずすべてのユーザーエージェントに適用されます。
オリジンはウェブのセキュリティモデルの基本的な通貨です。同じオリジンを共有するウェブプラットフォーム上の二つのアクターは、互いに信頼し、同じ権限を持っていると見なされます。異なるオリジンを持つアクターは互いに潜在的に敵対的であると見なされ、さまざまな程度で隔離されます。
例えば、bank.example.comでホストされているExample
Bankのウェブサイトが、charity.example.orgでホストされているExample CharityのウェブサイトのDOMを調べようとすると、"SecurityError"が発生し、DOMExceptionが発生します。
オリジンは次のいずれかです:
内部値であり、再作成できるシリアル化がなく、オリジンのシリアル化に基づいて"null"としてシリアル化されます。そのため、意味のある操作は等価性のテストのみです。
タプルは次の要素から構成されます:
オリジンは、複数のDocumentオブジェクト間で共有されることがあります。さらに、オリジンは通常不変です。ドメインだけがタプルオリジンを通じて変更でき、document.domainAPIを通じてのみ変更できます。
実効ドメインは、オリジン originを次のように計算します:
オリジンのシリアル化は、次のアルゴリズムを適用して得られる文字列です:
originが不透明なオリジンの場合、"null"を返します。
それ以外の場合、resultをoriginのスキームに設定します。
resultに"://"を追加します。
originのホストをresultに追加します。シリアライズされたものを追加します。
originのポートがnullでない場合、U+003Aコロン文字(:)とoriginのポートをresultに追加します。シリアライズされたものを追加します。
resultを返します。
シリアル化された("https",
"xn--maraa-rta.example", null, null)は"https://xn--maraa-rta.example"です。
かつてはオリジンのUnicodeシリアル化もありましたが、広く採用されることはありませんでした。
二つのオリジン、AとBが同一オリジンであると言われるのは、次のアルゴリズムがtrueを返す場合です:
AとBが同じ不透明なオリジンである場合、trueを返します。
falseを返します。
二つのオリジン、AとBが同一オリジンドメインであると言われるのは、次のアルゴリズムがtrueを返す場合です:
| A | B | 同一オリジン | 同一オリジンドメイン |
|---|---|---|---|
("https", "example.org", null, null)
| ("https", "example.org", null, null)
| ✅ | ✅ |
("https", "example.org", 314, null)
| ("https", "example.org", 420, null)
| ❌ | ❌ |
("https", "example.org", 314, "example.org")
| ("https", "example.org", 420, "example.org")
| ❌ | ✅ |
("https", "example.org", null, null)
| ("https", "example.org", null, "example.org")
| ✅ | ❌ |
("https", "example.org", null, "example.org")
| ("http", "example.org", null, "example.org")
| ❌ | ❌ |
スキームとホストとは、タプルの一つで、スキーム(ASCII文字列)とホスト(ホスト)から構成されます。
サイトとは、不透明なオリジンまたはスキームとホストのことです。
サイトを取得するには、オリジンoriginが与えられたとき、次の手順を実行します:
二つのサイト、AとBが同一サイトであると言われるのは、次のアルゴリズムがtrueを返す場合です:
AとBが同じ不透明なオリジンである場合、trueを返します。
AまたはBが不透明なオリジンである場合、falseを返します。
AとBのスキームが異なる場合、falseを返します。
trueを返します。
サイトのシリアル化は、次のアルゴリズムを適用して得られる文字列です:
siteが不透明なオリジンである場合、"null"を返します。
resultをsite[0]に設定します。
resultに"://"を追加します。
site[1]をシリアライズされたものとしてresultに追加します。
resultを返します。
シリアル化された値がサイトであることを文脈から明確にする必要があります。例えば、オリジン("https", "shop.example",
null, null)とサイト("https",
"shop.example")は、同じシリアル化を持つ可能性があります:"https://shop.example"。
二つのオリジン、AとBがスキームなしで同一サイトであると言われるのは、次のアルゴリズムがtrueを返す場合です:
二つのオリジン、AとBが同一サイトであると言われるのは、次のアルゴリズムがtrueを返す場合です:
同一オリジンおよび同一オリジンドメインの概念とは異なり、スキームなしで同一サイトおよび同一サイトでは、ポートとドメインの要素は無視されます。
URLで説明されている理由により、同一サイトおよびスキームなしで同一サイトの概念は、可能な限り避け、代わりに同一オリジンのチェックを使用することを推奨します。
wildlife.museum、museum、およびcomがパブリックサフィックスであり、example.comがそうでないことを前提とします:
| A | B | スキームなしで同一サイト | 同一サイト |
|---|---|---|---|
("https", "example.com")
| ("https", "sub.example.com")
| ✅ | ✅ |
("https", "example.com")
| ("https", "sub.other.example.com")
| ✅ | ✅ |
("https", "example.com")
| ("http", "non-secure.example.com")
| ✅ | ❌ |
("https", "r.wildlife.museum")
| ("https", "sub.r.wildlife.museum")
| ✅ | ✅ |
("https", "r.wildlife.museum")
| ("https", "sub.other.r.wildlife.museum")
| ✅ | ✅ |
("https", "r.wildlife.museum")
| ("https", "other.wildlife.museum")
| ❌ | ❌ |
("https", "r.wildlife.museum")
| ("https", "wildlife.museum")
| ❌ | ❌ |
("https", "wildlife.museum")
| ("https", "wildlife.museum")
| ✅ | ✅ |
("https", "example.com")
| ("https", "example.com.")
| ❌ | ❌ |
document.domain [ = domain ]
セキュリティチェックに使用される現在のドメインを返します。
サブドメインを削除する値に設定して、オリジンのドメインを変更し、同じドメインの他のサブドメインのページが互いにアクセスできるようにすることができます(同じことをする場合)。これにより、同じドメインの異なるホスト上のページが、互いのDOMに同期的にアクセスできるようになります。
サンドボックス化されたiframe、不透明なオリジンを持つDocument、およびブラウジングコンテキストを持たないDocumentでは、セッターが"SecurityError"例外をスローします。また、crossOriginIsolatedまたはoriginAgentClusterがtrueを返す場合、セッターは何もしません。
document.domainセッターの使用は避けてください。これは同一オリジンポリシーが提供するセキュリティ保護を損なうものです。特に、共有ホスティングを使用している場合には重大です。例えば、信頼できない第三者が同じIPアドレスで異なるポートにHTTPサーバーをホストできる場合、document.domainセッターが使用された後にオリジンを比較するときにポートが無視されるため、通常は同じホスト上の異なるサイトを保護する同一オリジン保護が機能しなくなります。
これらのセキュリティリスクのため、この機能はウェブプラットフォームから削除されつつあります。(これは何年もかかる長いプロセスです。)
代わりに、postMessage()やMessageChannelオブジェクトを使用して、安全にオリジン間の通信を行ってください。
domainゲッターの手順は次の通りです:
effectiveDomainがnullである場合、空の文字列を返します。
effectiveDomainをシリアライズして返します。
domainセッターの手順は次の通りです:
thisのブラウジングコンテキストがnullである場合、"SecurityError" DOMExceptionをスローします。
thisのアクティブなサンドボックスフラグセットにサンドボックス化されたdocument.domainブラウジングコンテキストフラグが設定されている場合、"SecurityError" DOMExceptionをスローします。
effectiveDomainがnullである場合、"SecurityError" DOMExceptionをスローします。
与えられた値がeffectiveDomainの登録可能なドメイン接尾辞でないか、等しくない場合、"SecurityError" DOMExceptionをスローします。
周囲のエージェントのエージェントクラスタのオリジンキー設定が trueである場合、何もしません。
スカラー値文字列 hostSuffixStringが、ホスト originalHostの登録可能なドメイン接尾辞であるか、等しいかどうかを判断するために:
hostSuffixStringが空文字列の場合、falseを返します。
hostSuffixをhostSuffixStringを解析した結果とします。
hostSuffixが失敗した場合、falseを返します。
hostSuffixがoriginalHostと等しくない場合:
hostSuffixまたはoriginalHostがドメインでない場合、falseを返します。
hostSuffixがU+002E (.)で始まり、originalHostの末尾と一致しない場合、falseを返します。
以下のいずれかがtrueである場合:
hostSuffixがhostSuffixのパブリックサフィックスと等しい。
hostSuffixがU+002E (.)で始まり、originalHostのパブリックサフィックスの末尾と一致する。
falseを返します。[URL]
アサート:originalHostのパブリックサフィックスがU+002E (.)で始まり、hostSuffixの末尾と一致します。
trueを返します。
| hostSuffixString | originalHost | 登録可能なドメイン接尾辞であるか、等しいかの結果 | メモ |
|---|---|---|---|
"0.0.0.0"
| 0.0.0.0
| ✅ | |
"0x10203"
| 0.1.2.3
| ✅ | |
"[0::1]"
| ::1
| ✅ | |
"example.com"
| example.com
| ✅ | |
"example.com"
| example.com.
| ❌ | 末尾のドットは重要です。 |
"example.com."
| example.com
| ❌ | |
"example.com"
| www.example.com
| ✅ | |
"com"
| example.com
| ❌ | 執筆時点では、comはパブリックサフィックスです。
|
"example"
| example
| ✅ | |
"compute.amazonaws.com"
| example.compute.amazonaws.com
| ❌ | 執筆時点では、*.compute.amazonaws.comはパブリックサフィックスです。
|
"example.compute.amazonaws.com"
| www.example.compute.amazonaws.com
| ❌ | |
"amazonaws.com"
| www.example.compute.amazonaws.com
| ❌ | |
"amazonaws.com"
| test.amazonaws.com
| ✅ | 執筆時点では、amazonaws.comは登録可能なドメインです。
|
window.originAgentCluster
このWindowが、オリジンキー付きのエージェントクラスタに属している場合にtrueを返します。このセクションで説明されている方法に従います。
セキュアなコンテキストで提供されるDocumentは、`Origin-Agent-Cluster` HTTPレスポンスヘッダーを使用して、オリジンキー付きのエージェントクラスタに配置するよう要求できます。このヘッダーは構造化されたヘッダーであり、その値はブール値でなければなりません。[STRUCTURED-FIELDS]
新しいDocumentオブジェクトを作成し初期化する処理モデルに従って、構造化されたヘッダーブール値のtrue値(つまり、`?1`)以外の値は無視されます。
このヘッダーを使用する結果として、生成されたDocumentのオリジンがエージェントクラスタキーとして設定され、対応するサイトではなくなります。観察可能な効果としては、document.domainを使用して同一オリジン制約を緩和することを試みても何も起こらず、同一サイトであってもクロスオリジンのDocumentにWebAssembly.Moduleオブジェクトを送信することはできません。この隔離により、ユーザーエージェントがプロセスやスレッドなど、エージェントクラスタに対応する実装固有のリソースをより効率的に割り当てることができる場合があります。
ブラウジングコンテキストグループ内では、`Origin-Agent-Cluster`ヘッダーを使用しても、同一オリジンのDocumentオブジェクトが異なるエージェントクラスタに入ることはありません。一方がヘッダーを送信し、他方が送信しなかったとしても、これは防止されます。歴史的エージェントクラスタキーのマップによって防止されます。
これは、以前に同一オリジンページでヘッダーが省略された場合、ヘッダーが設定されていても、originAgentClusterゲッターがfalseを返すことがあることを意味します。同様に、ヘッダーが設定されていなくてもtrueを返すことができます。
originAgentClusterゲッターの手順は、周囲のエージェントのエージェントクラスタがオリジンキー付きであるかを返すことです。
不透明なオリジンを持つDocumentは、無条件にオリジンキー付きと見なされます。これらのドキュメントに対してヘッダーは効果がなく、originAgentClusterゲッターは常にtrueを返します。
同様に、エージェントクラスタのクロスオリジン隔離モードが"none"でないDocumentも自動的にオリジンキー付きとなります。`Origin-Agent-Cluster`ヘッダーは、リソース割り当てに関する追加のヒントとして実装に有用な場合がありますが、`Cross-Origin-Opener-Policy`および`Cross-Origin-Embedder-Policy`ヘッダーを使用してクロスオリジン隔離を実現する場合、同じアドレス空間内のすべてがそこに参加することを保証するためのものであり、それを追加しても著者コードには追加の観察可能な効果はありません。
クロスオリジンオープナーポリシーの値により、トップレベルのブラウジングコンテキストでナビゲートされるドキュメントが、新しいトップレベルのブラウジングコンテキストと対応するグループを作成するよう強制することができます。可能な値は以下の通りです:
unsafe-none"
これは現在のデフォルトであり、ドキュメントは前のドキュメントと同じトップレベルのブラウジングコンテキストを占有します。ただし、そのドキュメントが異なるクロスオリジンオープナーポリシーを指定していない限り。
same-origin-allow-popups"
これにより、ドキュメントに対して新しいトップレベルのブラウジングコンテキストの作成が強制されます。ただし、前のドキュメントが同じクロスオリジンオープナーポリシーを指定しており、それらが同一オリジンである場合を除きます。
same-origin"
これは"same-origin-allow-popups"と同じ動作をしますが、追加で、作成される補助的なブラウジングコンテキストが、同じ同一オリジンのドキュメントを含み、かつ同じクロスオリジンオープナーポリシーを持つ必要があります。そうでない場合、オープナーに閉じた状態として表示されます。
same-origin-plus-COEP"
これは"same-origin"と同じ動作をしますが、新しいトップレベルのブラウジングコンテキストのグループのクロスオリジン隔離モードを"logical"または"concrete"のいずれかに設定します。
"same-origin-plus-COEP"は、`Cross-Origin-Opener-Policy`ヘッダーで直接設定することはできませんが、`Cross-Origin-Opener-Policy: same-origin`と、Cross-Origin-Embedder-Policy`ヘッダーを一緒に設定した結果として生じます。`クロスオリジン隔離と互換性がある`値が必要です。
クロスオリジンオープナーポリシーは以下で構成されます:
値、これはクロスオリジンオープナーポリシーの値であり、初期値は"unsafe-none"です。
レポートエンドポイント、これは文字列またはnullで、初期値はnullです。
レポートオンリーの値、これはクロスオリジンオープナーポリシーの値であり、初期値は"unsafe-none"です。
レポートオンリーのレポートエンドポイント、これは文字列またはnullで、初期値はnullです。
クロスオリジンオープナーポリシー値を一致させるには、クロスオリジンオープナーポリシーの値 A、オリジン originA、クロスオリジンオープナーポリシーの値 B、およびオリジン originBを指定します:
Aが"unsafe-none"であり、Bも"unsafe-none"である場合、trueを返します。
Aが"unsafe-none"であり、またはBが"unsafe-none"である場合、falseを返します。
AがBと一致し、originAがoriginBと同一オリジンである場合、trueを返します。
falseを返します。
Headers/Cross-Origin-Opener-Policy
すべての現行エンジンでサポートされています。
Documentのクロスオリジンオープナーポリシーは、`Cross-Origin-Opener-Policy` および `Cross-Origin-Opener-Policy-Report-Only`
HTTPレスポンスヘッダーから派生します。これらのヘッダーは構造化されたヘッダーであり、その値はトークンでなければなりません。[STRUCTURED-FIELDS]
有効なトークンの値は、オープナーポリシーの値です。また、トークンにはパラメーターが付与される場合もあります。これらの中で、"report-to"パラメーターには、適切なレポートエンドポイントを指定する有効なURL文字列が含まれることがあります。[REPORTING]
以下に説明する処理モデルに従い、ユーザーエージェントはこのヘッダーが無効な値を含む場合、このヘッダーを無視します。同様に、値がトークンとして解析できない場合、ユーザーエージェントはこのヘッダーを無視します。
クロスオリジンオープナーポリシーを取得するには、レスポンス responseと環境 reservedEnvironmentを指定します:
policyを新しいクロスオリジンオープナーポリシーとして設定します。
reservedEnvironmentが非セキュアなコンテキストである場合、policyを返します。
parsedItemを、responseのヘッダーリストから`Cross-Origin-Opener-Policy`および"item"を指定して構造化されたフィールド値を取得する結果として設定します。
parsedItemがnullでない場合、次の処理を行います:
parsedItem[0]が"same-origin"である場合、次の処理を行います:
coepをresponseおよびreservedEnvironmentからクロスオリジンエンベッダーポリシーを取得する結果として設定します。
coepの値がクロスオリジン隔離と互換性がある場合、policyの値を"same-origin-plus-COEP"に設定します。
それ以外の場合は、policyの値を"same-origin"に設定します。
parsedItem[0]が"same-origin-allow-popups"である場合、policyの値を"same-origin-allow-popups"に設定します。
parsedItem[1]["report-to"]が存在し、それが文字列である場合、policyのレポートエンドポイントをparsedItem[1]["report-to"]に設定します。
parsedItemを、responseのヘッダーリストから`Cross-Origin-Opener-Policy-Report-Only`および"item"を指定して構造化されたフィールド値を取得する結果として設定します。
parsedItemがnullでない場合、次の処理を行います:
parsedItem[0]が"same-origin"である場合、次の処理を行います:
coepをresponseおよびreservedEnvironmentからクロスオリジンエンベッダーポリシーを取得する結果として設定します。
coepの値がクロスオリジン隔離と互換性があるまたはcoepのレポートオンリーの値がクロスオリジン隔離と互換性がある場合、policyのレポートオンリーの値を"same-origin-plus-COEP"に設定します。
レポートオンリーのCOOPは、特別な"same-origin-plus-COEP"値を割り当てるために、レポートオンリーのCOEPも考慮します。これにより、開発者はCOOPとCOEPの展開順序により柔軟性を持つことができます。
それ以外の場合は、policyのレポートオンリーの値を"same-origin"に設定します。
parsedItem[0]が"same-origin-allow-popups"である場合、policyのレポートオンリーの値を"same-origin-allow-popups"に設定します。
parsedItem[1]["report-to"]が存在し、それが文字列である場合、policyのレポートオンリーのレポートエンドポイントをparsedItem[1]["report-to"]に設定します。
policyを返します。
COOP値がブラウジングコンテキストグループの切り替えを必要とするかを確認するには、ブール値のisInitialAboutBlank、2つのオリジン responseOriginとactiveDocumentNavigationOrigin、および2つのクロスオリジンオープナーポリシー値 responseCOOPValueとactiveDocumentCOOPValueを指定します:
マッチングの結果、activeDocumentCOOPValue、activeDocumentNavigationOrigin、responseCOOPValue、およびresponseOriginがtrueの場合、falseを返します。
以下のすべてがtrueの場合:
isInitialAboutBlankがtrueであること。
activeDocumentCOOPValueの値が"same-origin-allow-popups"であること。
responseCOOPValueが"unsafe-none"であること。
以上の場合は、falseを返します。
それ以外の場合、trueを返します。
レポートオンリーCOOPを施行するとブラウジングコンテキストグループの切り替えが必要かどうかを確認するには、ブール値のisInitialAboutBlank、2つのオリジン responseOriginとactiveDocumentNavigationOrigin、および2つのクロスオリジンオープナーポリシー responseCOOPとactiveDocumentCOOPを指定します:
COOP値がブラウジングコンテキストグループの切り替えを必要とするかを確認するの結果、isInitialAboutBlank、responseOrigin、activeDocumentNavigationOrigin、responseCOOPのレポートオンリー値とactiveDocumentCOOPReportOnlyのレポートオンリー値がfalseの場合、falseを返します。
レポートオンリーポリシーをマッチングすることで、ウェブサイトがすべてのページに同じレポートオンリークロスオリジンオープナーポリシーを指定し、これらのページ間のナビゲーションに対して違反レポートを受け取らないようにすることができます。
COOP値がブラウジングコンテキストグループの切り替えを必要とするかを確認するの結果、isInitialAboutBlank、responseOrigin、activeDocumentNavigationOrigin、responseCOOPの値とactiveDocumentCOOPReportOnlyのレポートオンリー値がtrueの場合、trueを返します。
COOP値がブラウジングコンテキストグループの切り替えを必要とするかを確認するの結果、isInitialAboutBlank、responseOrigin、activeDocumentNavigationOrigin、responseCOOPのレポートオンリー値とactiveDocumentCOOPReportOnlyの値がtrueの場合、trueを返します。
それ以外の場合、falseを返します。
クロスオリジンオープナーポリシーの施行結果は、次の構造体の項目を持つ構造体です:
ブール値のブラウジングコンテキストグループの切り替えが必要、初期値はfalse。
ブール値のレポートオンリーによるブラウジングコンテキストグループの切り替えが必要、初期値はfalse。
URLのurl。
オリジンのオリジン。
クロスオリジンオープナーポリシーのクロスオリジンオープナーポリシー。
ブール値の現在のコンテキストがナビゲーションソース、初期値はfalse。
レスポンスのクロスオリジンオープナーポリシーを適用するには、以下を実行します: ブラウジングコンテキスト browsingContext、 URL responseURL、 オリジン responseOrigin、 クロスオリジンオープナーポリシー responseCOOP、 クロスオリジンオープナーポリシーの適用結果 currentCOOPEnforcementResult、 リファラー referrer:
newCOOPEnforcementResultを新しいクロスオリジンオープナーポリシー施行結果として作成し、次の属性を持たせます:
isInitialAboutBlankをbrowsingContextのアクティブドキュメントの初期about:blankかどうかに設定します。
isInitialAboutBlankがtrueであり、browsingContextの初期URLがnullの場合、browsingContextの初期URLをresponseURLに設定します。
COOP値がブラウジングコンテキストグループの切り替えを必要とするかを確認するの結果、isInitialAboutBlank、currentCOOPEnforcementResultのクロスオリジンオープナーポリシーの値、currentCOOPEnforcementResultのオリジン、responseCOOPの値、およびresponseOriginがtrueの場合、次を実行します:
newCOOPEnforcementResultのブラウジングコンテキストグループの切り替えが必要をtrueに設定します。
browsingContextのグループのブラウジングコンテキストセットのサイズが1より大きい場合、次を実行します:
COOPレスポンスへのナビゲーション時のブラウジングコンテキストグループ切り替え違反レポートをキューに追加する
responseCOOP、"施行"、responseURL、currentCOOPEnforcementResultのURL、currentCOOPEnforcementResultのオリジン、responseOrigin、およびreferrerを使用して。
COOPレスポンスからのナビゲーション時のブラウジングコンテキストグループ切り替え違反レポートをキューに追加する
currentCOOPEnforcementResultのクロスオリジンオープナーポリシー、"施行"、currentCOOPEnforcementResultのURL、responseURL、currentCOOPEnforcementResultのオリジン、responseOrigin、およびcurrentCOOPEnforcementResultの現在のコンテキストがナビゲーションソースを使用して。
レポートオンリーCOOPを施行するとブラウジングコンテキストグループの切り替えが必要かどうかを確認するの結果、isInitialAboutBlank、responseOrigin、currentCOOPEnforcementResultのオリジン、responseCOOP、およびcurrentCOOPEnforcementResultのクロスオリジンオープナーポリシーがtrueの場合、次を実行します:
resultのレポートオンリーによるブラウジングコンテキストグループの切り替えが必要をtrueに設定します。
もしbrowsingContextのグループのブラウジングコンテキストセットのサイズが1より大きい場合、次の操作を実行します:
COOPレスポンスへのナビゲーション時のブラウジングコンテキストグループ切り替え違反レポートをキューに追加する
responseCOOP、"報告"、responseURL、currentCOOPEnforcementResultのURL、currentCOOPEnforcementResultのオリジン、responseOrigin、およびreferrerを使用して。
COOPレスポンスからのナビゲーション時のブラウジングコンテキストグループ切り替え違反レポートをキューに追加する
currentCOOPEnforcementResultのクロスオリジンオープナーポリシー、"報告"、currentCOOPEnforcementResultのURL、responseURL、currentCOOPEnforcementResultのオリジン、responseOrigin、およびcurrentCOOPEnforcementResultの現在のコンテキストがナビゲーションソースを使用して。
それ以外の場合、newCOOPEnforcementResultを返します。
ナビゲーションレスポンスに使用するブラウジングコンテキストを取得するには、ブラウジングコンテキスト browsingContext、サンドボックスフラグセット sandboxFlags、クロスオリジンオープナーポリシー navigationCOOP、およびクロスオリジンオープナーポリシー施行結果 coopEnforcementResultを指定します:
browsingContextがトップレベルブラウジングコンテキストでない場合、browsingContextを返します。
coopEnforcementResultのブラウジングコンテキストグループの切り替えが必要がfalseの場合:
coopEnforcementResultのレポートオンリーによるブラウジングコンテキストグループの切り替えが必要がtrueである場合、browsing contextの仮想ブラウジングコンテキストグループIDを新しい一意の識別子に設定します。
browsingContextを返します。
newBrowsingContextを新しいトップレベルブラウジングコンテキストとドキュメントを作成した最初の戻り値として設定します。
この場合、ブラウジングコンテキストグループのスワップを行います。browsingContextは、これから作成されるドキュメントでは使用されません。もし他のドキュメント(例えば、前進/後退キャッシュにあるものなど)でも使用されない場合、ユーザーエージェントはこの時点でそれを破棄するかもしれません。
navigationCOOPの値が"same-origin-plus-COEP"である場合、newBrowsingContextのグループのクロスオリジン分離モードを"logical"または"concrete"のいずれかに設定します。どちらを選ぶかは実装依存です。
一部のプラットフォームでは、クロスオリジン分離機能に必要なセキュリティ特性を提供するのが困難です。"concrete"はそれにアクセスを許可し、"logical"は許可しません。
sandboxFlagsが空でない場合、次を実行します:
アサート:navigationCOOPの値が"unsafe-none"であることを確認します。
アサート:newBrowsingContextのポップアップサンドボックスフラグセットが空であることを確認します。
newBrowsingContextのポップアップサンドボックスフラグセットをsandboxFlagsのクローンに設定します。
newBrowsingContextを返します。
アクセサーとアクセス先の関係は、アクセスが発生した2つのブラウジングコンテキスト間の関係を説明する列挙型です。次の値を取ることができます:
アクセサーのブラウジングコンテキストまたはそのいずれかの祖先が、アクセス先のオープナーブラウジングコンテキストの最上位ブラウジングコンテキストである場合。
アクセス先のブラウジングコンテキストまたはそのいずれかの祖先が、アクセサーのオープナーブラウジングコンテキストの最上位ブラウジングコンテキストである場合。
アクセサーのブラウジングコンテキストと、アクセス先のブラウジングコンテキストの間にオープナー関係がない場合。
2つのブラウジングコンテキスト間のアクセスが報告されるべきかを確認するために、2つのブラウジングコンテキスト accessor および accessed、JavaScriptプロパティ名P、および環境設定オブジェクト environmentが与えられたとします:
P が クロスオリジンでアクセス可能なウィンドウプロパティ名でない場合、処理を終了します。
断言します:accessor のアクティブなドキュメントとaccessed のアクティブなドキュメントが両方とも完全にアクティブであることを。
accessorTopDocument を、accessor の最上位ブラウジングコンテキストのアクティブなドキュメントとします。
accessorInclusiveAncestorOrigins を、accessor のアクティブなドキュメントの各包括的祖先ナビゲーブルの起源を取得して得られたリストとします。
accessedTopDocument を、accessed の最上位ブラウジングコンテキストのアクティブなドキュメントとします。
accessedInclusiveAncestorOrigins を、accessed のアクティブなドキュメントの各包括的祖先ナビゲーブルの起源を取得して得られたリストとします。
いずれかのaccessorInclusiveAncestorOriginsが、accessorTopDocumentの起源と同じ起源でない場合、または、いずれかのaccessedInclusiveAncestorOriginsがaccessedTopDocumentの起源と同じ起源でない場合、処理を終了します。
これにより、クロスオリジンのインラインフレームに関する情報が、クロスオリジンオープナーポリシーレポートを持つ最上位フレームに漏れるのを防ぎます。
accessor の最上位ブラウジングコンテキストの仮想ブラウジングコンテキストグループIDが、accessed の最上位ブラウジングコンテキストの仮想ブラウジングコンテキストグループIDと一致する場合、処理を終了します。
accessorAccessedRelationship を新しいアクセサーとアクセス先の関係として、値をなしとします。
もし、accessed の最上位ブラウジングコンテキストのオープナーブラウジングコンテキストがaccessorであるか、accessorの祖先である場合、accessorAccessedRelationshipをアクセサーがオープナーに設定します。
もし、accessor の最上位ブラウジングコンテキストのオープナーブラウジングコンテキストがaccessedであるか、accessedの祖先である場合、accessorAccessedRelationshipをアクセサーがオープンされた側に設定します。
違反レポートをキューに入れる:accessorAccessedRelationship、accessorTopDocumentのクロスオリジンオープナーポリシー、accessedTopDocumentのクロスオリジンオープナーポリシー、accessor のアクティブなドキュメントのURL、accessedのアクティブなドキュメントのURL、accessor の最上位ブラウジングコンテキストの初期URL、accessed の最上位ブラウジングコンテキストの初期URL、accessor のアクティブなドキュメントの起源、accessed のアクティブなドキュメントの起源、accessor の最上位ブラウジングコンテキストの作成時のオープナーの起源、accessed の最上位ブラウジングコンテキストの作成時のオープナーの起源、accessorTopDocumentのリファラー、accessedTopDocumentのリファラー、P、およびenvironment。
レポートで送信するURLをサニタイズするには、URL urlが与えられた場合:
sanitizedURL を url のコピーとします。
ユーザー名を設定し、sanitizedURL に空文字列を設定します。
パスワードを設定し、sanitizedURL に空文字列を設定します。
COOPレスポンスにナビゲートする際のブラウジングコンテキストグループの切り替えに関する違反レポートをキューに入れるには、クロスオリジンオープナーポリシー coop、文字列disposition、URL coopURL、URL previousResponseURL、2つの起源 coopOrigin と previousResponseOrigin、およびリファラー referrerが与えられた場合:
もしcoop のレポートエンドポイントが null である場合、処理を終了します。
coopValue を coop の値とします。
もしdisposition が "reporting" である場合、coopValue を coop のレポート専用の値に設定します。
serializedReferrer を空文字列とします。
もしreferrer が URLである場合、serializedReferrer を referrer のシリアル化に設定します。
body を以下のプロパティを含む新しいオブジェクトとします:
| キー | 値 |
|---|---|
| disposition | disposition |
| effectivePolicy | coopValue |
| previousResponseURL | もし coopOrigin と previousResponseOrigin が同じ起源である場合、これはpreviousResponseURL のサニタイズであり、そうでない場合はnullです。 |
| referrer | serializedReferrer |
| type | "navigation-to-response"
|
レポートをキューに入れる:body を "coop"
として、coop のレポートエンドポイントにcoopURLと共に送信します。
COOPレスポンスからのナビゲーション時にブラウジングコンテキストグループの切り替えが発生した場合の違反レポートをキューに入れるには、クロスオリジンオープナーポリシー coop、文字列disposition、URL coopURL、URL nextResponseURL、2つの起源 coopOrigin と nextResponseOrigin、およびブール値isCOOPResponseNavigationSourceが与えられた場合:
もしcoop のレポートエンドポイントが null である場合、処理を終了します。
coopValue を coop の値とします。
もしdisposition が "reporting" である場合、coopValue を coop のレポート専用の値に設定します。
body を以下のプロパティを含む新しいオブジェクトとします:
| キー | 値 |
|---|---|
| disposition | disposition |
| effectivePolicy | coopValue |
| nextResponseURL | もしcoopOriginとnextResponseOriginが同じ起源であるか、isCOOPResponseNavigationSourceがtrueである場合、これはpreviousResponseURLのサニタイズであり、そうでない場合はnullです。 |
| type | "navigation-from-response"
|
レポートをキューに入れる:bodyを"coop"として、coopのレポートエンドポイントにcoopURLと共に送信します。
アクセスに関する違反レポートをキューに入れるには、アクセサーとアクセスされた要素の関係 accessorAccessedRelationship、2つのクロスオリジンオープナーポリシー accessorCOOP および accessedCOOP、4つのURL accessorURL、accessedURL、accessorInitialURL、accessedInitialURL、4つの起源 accessorOrigin、accessedOrigin、accessorCreatorOrigin および accessedCreatorOrigin、2つのリファラー accessorReferrer および accessedReferrer、文字列propertyName、および環境設定オブジェクト environmentが与えられた場合:
もしcoop のレポートエンドポイントが null である場合、処理を終了します。
coopValue を coop の値とします。
もしdisposition が "reporting" である場合、coopValue を coop のレポート専用の値に設定します。
もしaccessorAccessedRelationship が アクセサーがオープナーである場合:
開かれたウィンドウへのアクセスに関する違反レポートをキューに入れる:accessorCOOP、accessorURL、accessedURL、accessedInitialURL、accessorOrigin、accessedOrigin、accessedCreatorOrigin、propertyName、およびenvironmentが与えられた場合。
オープナーからのアクセスに関する違反レポートをキューに入れる:accessedCOOP、accessedURL、accessorURL、accessedOrigin、accessorOrigin、propertyName、およびaccessedReferrerが与えられた場合。
それ以外の場合、もしaccessorAccessedRelationship が アクセサーがオペニーである場合:
オープナーへのアクセスに関する違反レポートをキューに入れる:accessorCOOP、accessorURL、accessedURL、accessorOrigin、accessedOrigin、propertyName、accessorReferrer、およびenvironmentが与えられた場合。
開かれたウィンドウからのアクセスに関する違反レポートをキューに入れる:accessedCOOP、accessedURL、accessorURL、accessorInitialURL、accessedOrigin、accessorOrigin、accessorCreatorOrigin、およびpropertyNameが与えられた場合。
それ以外の場合:
他のウィンドウへのアクセスに関する違反レポートをキューに入れる:accessorCOOP、accessorURL、accessedURL、accessorOrigin、accessedOrigin、propertyName、およびenvironmentが与えられた場合。
他のウィンドウからのアクセスに関する違反レポートをキューに入れる:accessedCOOP、accessedURL、accessorURL、accessedOrigin、accessorOrigin、およびpropertyNameが与えられた場合。
オープナーへのアクセスに関する違反レポートをキューに入れるには、クロスオリジンオープナーポリシー coop、2つのURL coopURL および openerURL、2つの起源 coopOrigin および openerOrigin、文字列propertyName、リファラー referrer、および環境設定オブジェクト environmentが与えられた場合:
sourceFile、lineNumber、およびcolumnNumberは、このレポートを引き起こした関連するスクリプトのURLおよび問題のある位置とします。
serializedReferrerを空の文字列とします。
もしreferrerがURLである場合、serializedReferrerをreferrerのシリアライゼーションに設定します。
bodyを以下のプロパティを含む新しいオブジェクトとします:
| キー | 値 |
|---|---|
| disposition | "reporting"
|
| effectivePolicy | coop のレポート専用の値 |
| property | propertyName |
| openerURL | もしcoopOrigin と openerOrigin が同じ起源である場合、これはopenerURL のサニタイズであり、そうでない場合はnullです。 |
| referrer | serializedReferrer |
| sourceFile | sourceFile |
| lineNumber | lineNumber |
| columnNumber | columnNumber |
| type | "access-to-opener"
|
レポートをキューに入れる:bodyを"coop"として、coopのレポートエンドポイントにcoopURLとenvironmentと共に送信します。
開かれたウィンドウへのアクセスに関する違反レポートをキューに入れるには、クロスオリジンオープナーポリシー coop、3つのURL coopURL、openedWindowURL および initialWindowURL、3つの起源 coopOrigin、openedWindowOrigin、およびopenerInitialOrigin、文字列propertyName、および環境設定オブジェクト environmentが与えられた場合:
sourceFile、lineNumber、およびcolumnNumberは、このレポートを引き起こした関連するスクリプトのURLおよび問題のある位置とします。
bodyを以下のプロパティを含む新しいオブジェクトとします:
| キー | 値 |
|---|---|
| disposition | "reporting"
|
| effectivePolicy | coop のレポート専用の値 |
| property | propertyName |
| openedWindowURL | もしcoopOrigin と openedWindowOrigin が同じ起源である場合、これはopenedWindowURL のサニタイズであり、そうでない場合はnullです。 |
| openedWindowInitialURL | もしcoopOrigin と openerInitialOrigin が同じ起源である場合、これはinitialWindowURL のサニタイズであり、そうでない場合はnullです。 |
| sourceFile | sourceFile |
| lineNumber | lineNumber |
| columnNumber | columnNumber |
| type | "access-to-opener"
|
レポートをキューに入れる:bodyを"coop"として、coopのレポートエンドポイントにcoopURLとenvironmentと共に送信します。
他のウィンドウへのアクセスに関する違反レポートをキューに入れるには、クロスオリジンオープナーポリシー coop、2つのURL coopURL および otherURL、2つの起源 coopOrigin および otherOrigin、文字列propertyName、および環境設定オブジェクト environmentが与えられた場合:
sourceFile、lineNumber、およびcolumnNumberは、このレポートを引き起こした関連するスクリプトのURLおよび問題のある位置とします。
bodyを以下のプロパティを含む新しいオブジェクトとします:
| キー | 値 |
|---|---|
| disposition | "reporting"
|
| effectivePolicy | coop のレポート専用の値 |
| property | propertyName |
| otherURL | もしcoopOrigin と otherOrigin が同じ起源である場合、これはotherURL のサニタイズであり、そうでない場合はnullです。 |
| sourceFile | sourceFile |
| lineNumber | lineNumber |
| columnNumber | columnNumber |
| type | "access-to-opener"
|
レポートをキューに入れる:bodyを"coop"として、coopのレポートエンドポイントにcoopURLとenvironmentと共に送信します。
オープナーからのアクセスに関する違反レポートをキューに入れるには、クロスオリジンオープナーポリシー coop、2つのURL coopURL および openerURL、2つの起源 coopOrigin および openerOrigin、文字列propertyName、およびリファラー referrerが与えられた場合:
もしcoop のレポートエンドポイントがnullである場合、リターンします。
serializedReferrerを空の文字列とします。
もしreferrerがURLである場合、serializedReferrerをreferrerのシリアライゼーションに設定します。
bodyを以下のプロパティを含む新しいオブジェクトとします:
| キー | 値 |
|---|---|
| disposition | "reporting"
|
| effectivePolicy | coop のレポート専用の値 |
| property | propertyName |
| openerURL | もしcoopOrigin と openerOrigin が同じ起源である場合、これはopenerURL のサニタイズであり、そうでない場合はnullです。 |
| referrer | serializedReferrer |
| type | "access-to-opener"
|
レポートをキューに入れる:bodyを"coop"として、coopのレポートエンドポイントにcoopURLと共に送信します。
開かれたウィンドウからのアクセスに関する違反レポートをキューに入れるには、クロスオリジンオープナーポリシー coop、3つのURL coopURL、openedWindowURL および initialWindowURL、3つの起源 coopOrigin、openedWindowOrigin、およびopenerInitialOrigin、文字列propertyNameが与えられた場合:
もしcoop のレポートエンドポイントがnullである場合、リターンします。
bodyを以下のプロパティを含む新しいオブジェクトとします:
| キー | 値 |
|---|---|
| disposition | "reporting"
|
| effectivePolicy | coopValue |
| property | coop のレポート専用の値 |
| openedWindowURL | もしcoopOrigin と openedWindowOrigin が同じ起源である場合、これはopenedWindowURL のサニタイズであり、そうでない場合はnullです。 |
| openedWindowInitialURL | もしcoopOrigin と openerInitialOrigin が同じ起源である場合、これはinitialWindowURL のサニタイズであり、そうでない場合はnullです。 |
| type | "access-to-opener"
|
レポートをキューに入れる:bodyを"coop"として、coopのレポートエンドポイントにcoopURLとenvironmentと共に送信します。
他のウィンドウからのアクセスに関する違反レポートをキューに入れるには、クロスオリジンオープナーポリシー coop、2つのURL coopURL および otherURL、2つの起源 coopOrigin および otherOrigin、文字列propertyNameが与えられた場合:
もしcoop のレポートエンドポイントがnullである場合、リターンします。
bodyを以下のプロパティを含む新しいオブジェクトとします:
| キー | 値 |
|---|---|
| disposition | "reporting"
|
| effectivePolicy | coop のレポート専用の値 |
| property | propertyName |
| otherURL | もしcoopOrigin と otherOrigin が同じ起源である場合、これはotherURL のサニタイズであり、そうでない場合はnullです。 |
| type | "access-to-opener"
|
レポートをキューに入れる:bodyを"coop"として、coopのレポートエンドポイントにcoopURLと共に送信します。
Headers/Cross-Origin-Embedder-Policy
すべての現在のエンジンでサポートされています。
埋め込みポリシー値は、リソース所有者からの明示的な許可なしにクロスオリジンリソースの取得を制御する3つの文字列の1つです。
unsafe-none"
これがデフォルト値です。この値が使用されている場合、クロスオリジンリソースは、CORSプロトコルまたは
`クロスオリジンリソースポリシー`
ヘッダーを通じて明示的な許可を与えずに取得できます。
require-corp"
この値が使用されている場合、クロスオリジンリソースの取得には、サーバーのCORSプロトコルまたは
`クロスオリジンリソースポリシー`
ヘッダーを通じての明示的な許可が必要です。
credentialless"
この値が使用されている場合、クロスオリジンのno-CORSリソースの取得時にクレデンシャルが省略されます。その代わりに、明示的な`クロスオリジンリソースポリシー`
ヘッダーは必要ありません。クレデンシャルを伴うその他のリクエストには、サーバーのCORSプロトコルまたは`クロスオリジンリソースポリシー`
ヘッダーを通じての明示的な許可が必要です。
"credentialless"をサポートする前に、
実装者は以下の両方をサポートすることを強く推奨します:
そうでなければ、攻撃者がクライアントのネットワーク位置を利用して、クロスオリジン分離機能を使用して非公開リソースを読み取ることができる可能性があります。
埋め込みポリシー値は、
"credentialless"または
"require-corp"である場合、クロスオリジン分離と互換性があると見なされます。
埋め込みポリシーは以下で構成されます:
値、これは埋め込みポリシー値
であり、最初は
"unsafe-none"です。
レポートエンドポイント文字列、最初は空の文字列です。
レポート専用値、これは埋め込みポリシー値であり、
最初は"unsafe-none"です。
レポート専用レポートエンドポイント文字列、最初は空の 文字列です。
"coep"レポートタイプは、その値が"coep"であるレポートタイプです。
これはReportingObserverから見えるものです。
`Cross-Origin-Embedder-Policy`および`Cross-Origin-Embedder-Policy-Report-Only` HTTPレスポンスヘッダーは、埋め込みポリシーを環境設定オブジェクトに対して宣言するためにサーバーが使用できるものです。これらのヘッダーは構造化ヘッダーであり、その値はトークンでなければなりません。
[STRUCTURED-FIELDS]
有効なトークンの値は埋め込みポリシー値です。このトークンにはパラメータを付けることもできます。その中でも`report-to`パラメータは、適切なレポートエンドポイントを識別する有効なURL文字列を持つことができます。[REPORTING]
処理モデルは、トークンとして解析できないヘッダーが存在する場合に、"unsafe-none"をデフォルトとして「オープンに失敗」します。これは、特定のレスポンスに含まれる複数の`Cross-Origin-Embedder-Policy`ヘッダーが組み合わさって意図しないリストが作成された場合を含みます:
`Cross-Origin-Embedder-Policy`
| 最終的な埋め込みポリシー値 |
|---|---|
| ヘッダーが提供されない場合 | "unsafe-none"
|
`require-corp`
| "require-corp"
|
`unknown-value`
| "unsafe-none"
|
`require-corp, unknown-value`
| "unsafe-none"
|
`unknown-value, unknown-value`
| "unsafe-none"
|
`unknown-value, require-corp`
| "unsafe-none"
|
`require-corp, require-corp`
| "unsafe-none"
|
(同じことが`Cross-Origin-Embedder-Policy-Report-Only`にも当てはまります。)
埋め込みポリシーを取得するには、レスポンス responseおよび環境 environmentから以下を実行します:
policyを新しい埋め込みポリシーとします。
environmentが非セキュアコンテキストである場合、policyを返します。
parsedItemを、`Cross-Origin-Embedder-Policy`および"item"を使用して構造化フィールド値を取得する結果とします。
responseのヘッダーリストから取得します。
もしparsedItemがnullでなく、かつparsedItem[0]がクロスオリジン分離と互換性がある場合:
parsedItemを、`Cross-Origin-Embedder-Policy-Report-Only`および"item"
を使用して構造化フィールド値を取得する結果とします。
responseのヘッダーリストから取得します。
もしparsedItemがnullでなく、かつparsedItem[0]がクロスオリジン分離と互換性がある場合:
policyを返します。
レスポンス response、ナビゲーション可能 navigable、および埋め込みポリシー responsePolicyが与えられた場合、ナビゲーションレスポンスの埋め込みポリシー遵守状況をチェックするには:
navigableが子ナビゲーション可能でない場合、trueを返します。
parentPolicyをnavigableのコンテナドキュメントのポリシーコンテナの埋め込みポリシーとします。
もしparentPolicyのレポート専用の値がクロスオリジン分離と互換性があるが、responsePolicyの値が互換性がない場合、クロスオリジン埋め込みポリシー継承違反をキューに入れ、response、"navigation"、parentPolicyのレポート専用の報告エンドポイント、"reporting"、およびnavigableのコンテナドキュメントの関連する設定オブジェクトを指定します。
もしparentPolicyの値がクロスオリジン分離と互換性がない、またはresponsePolicyの値がクロスオリジン分離と互換性がある場合、trueを返します。
クロスオリジン埋め込みポリシー継承違反をキューに入れ、response、"navigation"、parentPolicyの報告エンドポイント、"enforce"、およびnavigableのコンテナドキュメントの関連する設定オブジェクトを指定します。
falseを返します。
グローバルオブジェクトの埋め込みポリシーをチェックするには、WorkerGlobalScope
workerGlobalScope、環境設定オブジェクト owner、およびレスポンス responseが与えられた場合:
workerGlobalScopeがDedicatedWorkerGlobalScopeオブジェクトでない場合、trueを返します。
policyをworkerGlobalScopeの埋め込みポリシーとします。
もしownerPolicyのレポート専用の値がクロスオリジン分離と互換性があるが、policyの値が互換性がない場合、クロスオリジン埋め込みポリシー継承違反をキューに入れ、response、"worker initialization"、ownerPolicyのレポート専用の報告エンドポイント、"reporting"、およびownerを指定します。
もしownerPolicyの値がクロスオリジン分離と互換性がない、またはpolicyの値がクロスオリジン分離と互換性がある場合、trueを返します。
クロスオリジン埋め込みポリシー継承違反をキューに入れ、response、"worker initialization"、ownerPolicyの報告エンドポイント、"enforce"、およびownerを指定します。
falseを返します。
レスポンス response、文字列type、文字列endpoint、文字列disposition、および環境設定オブジェクト settingsが与えられた場合、クロスオリジン埋め込みポリシー継承違反をキューに入れるには:
レポート用にレスポンスURLをシリアル化する結果をresponseに対してserializedとします。
以下のプロパティを含む新しいオブジェクトをbodyとします:
| key | value |
|---|---|
| type | type |
| blockedURL | serialized |
| disposition | disposition |
キューに追加
bodyを"coep"
レポートタイプとして、settingsのendpointに対して。
サンドボックス化フラグセットは、以下のいずれか、または複数のフラグを持つセットであり、信頼できない可能性のあるリソースの機能を制限するために使用されます:
このフラグは、サンドボックス化されたブラウジングコンテキスト自体以外のブラウジングコンテキスト(またはその中にさらにネストされたブラウジングコンテキスト)、補助ブラウジングコンテキスト(次に定義されるサンドボックス化された補助ナビゲーションブラウジングコンテキストフラグによって保護されています)、およびトップレベルのブラウジングコンテキスト(以下で定義されるユーザーアクティベーションなしでのサンドボックス化されたトップレベルナビゲーションブラウジングコンテキストフラグおよびユーザーアクティベーションありでのサンドボックス化されたトップレベルナビゲーションブラウジングコンテキストフラグによって保護されています)へのナビゲーションを防ぎます。
もしサンドボックス化された補助ナビゲーションブラウジングコンテキストフラグが設定されていない場合でも、特定のケースではポップアップ(新しいトップレベルブラウジングコンテキスト)を開くことが許可されます。これらのブラウジングコンテキストには、作成時に設定される1つの許可されたサンドボックス化されたナビゲータがあり、それによって作成したブラウジングコンテキストが実際にナビゲートできるようになります。(そうでなければ、サンドボックス化されたナビゲーションブラウジングコンテキストフラグが、それらが開かれたとしてもナビゲートを防ぐことになります。)
このフラグは、新しい補助ブラウジングコンテキストを作成することを防ぎます。例えば、target属性やwindow.open()メソッドを使用することです。
このフラグは、トップレベルブラウジングコンテキストをナビゲートすることを防ぎます。また、トップレベルブラウジングコンテキストを閉じることを防ぎます。これは、サンドボックス化されたブラウジングコンテキストのアクティブウィンドウが一時的なアクティベーションを持たない場合にのみ参照されます。
ユーザーアクティベーションなしでのサンドボックス化されたトップレベルナビゲーションブラウジングコンテキストフラグが設定されていない場合、コンテンツはトップレベルブラウジングコンテキストをナビゲートできますが、他のブラウジングコンテキストは引き続きサンドボックス化されたナビゲーションブラウジングコンテキストフラグやおそらくサンドボックス化された補助ナビゲーションブラウジングコンテキストフラグによって保護されます。
このフラグは、トップレベルブラウジングコンテキストをナビゲートすることを防ぎます。また、トップレベルブラウジングコンテキストを閉じることを防ぎます。これは、サンドボックス化されたブラウジングコンテキストのアクティブウィンドウが一時的なアクティベーションを持つ場合にのみ参照されます。
ユーザーアクティベーションなしでのサンドボックス化されたトップレベルナビゲーションブラウジングコンテキストフラグと同様に、このフラグはトップレベルブラウジングコンテキストのみに影響します。設定されていない場合、他のブラウジングコンテキストは他のフラグによって保護されている可能性があります。
このフラグは、コンテンツを不透明なオリジンに強制し、同じオリジンの他のコンテンツへのアクセスを防ぎます。
このフラグはまた、スクリプトがdocument.cookieのIDL属性を読み書きすることを防ぎ、localStorageへのアクセスをブロックします。
このフラグはフォームの送信をブロックします。
このフラグはポインターロックAPIを無効にします。[POINTERLOCK]
このフラグはスクリプトの実行をブロックします。
このフラグは、ビデオの自動再生やフォームコントロールの自動フォーカスなど、自動的にトリガーされる機能をブロックします。
document.domainブラウジングコンテキストフラグこのフラグは、document.domainセッターの使用を防ぎます。
このフラグは、作成した補助ブラウジングコンテキストがコンテンツのアクティブなサンドボックス化フラグセットを継承することを保証することで、サンドボックスから逃れることを防ぎます。
このフラグは、次の機能を使用してモーダルダイアログを作成することを防ぎます:
このフラグは、画面の向きのロック機能を無効にします。[SCREENORIENTATION]
このフラグは、プレゼンテーションAPIを無効にします。[PRESENTATION]
このフラグは、ダウンロードリンクやナビゲーションを通じてダウンロードを開始またはインスタンス化することを防ぎます。これはダウンロードとして処理されるナビゲーションに該当します。
このフラグは、非fetchスキームへのナビゲーションが外部ソフトウェアに引き渡されることを防ぎます。
ユーザーエージェントが文字列input、およびサンドボックス化フラグセット outputが与えられたときにサンドボックス化ディレクティブを解析するために実行するステップ:
ASCIIホワイトスペースでinputを分割してtokensを取得します。
outputを空にします。
次のフラグをoutputに追加します:
allow-popupsキーワードが含まれている場合を除きます。allow-top-navigationキーワードが含まれている場合を除きます。allow-top-navigation-by-user-activationキーワード、またはallow-top-navigationキーワードが含まれている場合を除きます。
allow-same-originキーワードが含まれている場合を除きます。allow-formsキーワードが含まれている場合を除きます。allow-pointer-lockキーワードが含まれている場合を除きます。allow-scriptsキーワードが含まれている場合を除きます。allow-scriptsキーワードが含まれている場合を除きます。
document.domainブラウジングコンテキストフラグ
allow-popups-to-escape-sandboxキーワードが含まれている場合を除きます。
allow-modalsキーワードが含まれている場合を除きます。allow-orientation-lockキーワードが含まれている場合を除きます。allow-presentationキーワードが含まれている場合を除きます。allow-downloadsキーワードが含まれている場合を除きます。allow-top-navigation-to-custom-protocolsキーワード、allow-popupsキーワード、またはallow-top-navigationキーワードが含まれている場合を除きます。
各トップレベルブラウジングコンテキストには、ポップアップサンドボックス化フラグセットがあり、これはサンドボックス化フラグセットです。ブラウジングコンテキストが作成されると、そのポップアップサンドボックス化フラグセットは空でなければなりません。これはナビゲート可能なものを選択するためのルールとナビゲーション応答に使用するブラウジングコンテキストを取得するアルゴリズムによって設定されます。
各iframe要素には、iframeサンドボックス化フラグセットがあり、これはサンドボックス化フラグセットです。任意の時点で設定されているiframeサンドボックス化フラグセット内のフラグは、iframe要素のsandbox属性によって決定されます。
各Documentには、アクティブなサンドボックス化フラグセットがあり、これはサンドボックス化フラグセットです。Documentが作成されるとき、そのアクティブなサンドボックス化フラグセットは空でなければなりません。これはナビゲーションアルゴリズムによって設定されます。
各CSPリストcspListには、CSP由来のサンドボックス化フラグがあり、これはサンドボックス化フラグセットです。これは以下のアルゴリズムの戻り値です:
directivesを空の順序付けられたセットにします。
各cspList内のポリシーに対して:
もしdirectivesが空である場合、空のサンドボックス化フラグセットを返します。
directiveをdirectives[directivesのサイズ − 1]に設定します。
directiveに対してサンドボックス化ディレクティブを解析する結果を返します。
作成サンドボックス化フラグを決定するために、ブラウジングコンテキストbrowsing contextに対して、nullまたは要素embedderが与えられたとき、以下のサンドボックス化フラグセットに存在するフラグの和を返します:
もしembedderがnullの場合、そのbrowsing contextのポップアップサンドボックス化フラグセットに設定されたフラグ。
もしembedderが要素である場合、そのembedderのiframeサンドボックス化フラグセットに設定されたフラグ。
もしembedderが要素である場合、そのembedderのノードドキュメントのアクティブなサンドボックス化フラグセットに設定されたフラグ。
ポリシーコンテナとは、構造体であり、Document、WorkerGlobalScope、またはWorkletGlobalScopeに適用されるポリシーを含んでいます。これは以下の項目を持ちます。
CSPリスト、これはCSPリストです。初期状態では空です。
リファラーポリシー、これはリファラーポリシーです。初期状態ではデフォルトのリファラーポリシーです。
他のポリシーをポリシーコンテナに移動します。
ポリシーコンテナをクローンするには、ポリシーコンテナpolicyContainerを指定します。
URL urlが履歴にポリシーコンテナを保存する必要があるかどうかを判断するには:
フェッチレスポンスからポリシーコンテナを作成するには、レスポンスresponseと環境またはnullenvironmentを指定します。
もしresponseのURLのスキームが「blob」である場合、クローンを返します。
responseのURLのBlob URLエントリの環境のポリシーコンテナの。
新しいポリシーコンテナをresultとします。
resultのCSPリストを、responseを指定してレスポンスのコンテンツセキュリティポリシーを解析する結果に設定します。
もしenvironmentがnullでない場合、resultの埋め込みポリシーをresponseとenvironmentを指定して埋め込みポリシーを取得する結果に設定します。そうでなければ、「unsafe-none」に設定します。
resultのリファラーポリシーを、responseを指定して「Referrer-Policy」ヘッダーを解析する結果に設定します。 [REFERRERPOLICY]
resultを返します。
ナビゲーションパラメータポリシーコンテナを決定するには、URLresponseURLと、4つのポリシーコンテナまたはnullのhistoryPolicyContainer、initiatorPolicyContainer、parentPolicyContainer、およびresponsePolicyContainerを指定します。
もしhistoryPolicyContainerがnullでない場合:
アサート:responseURLが履歴にポリシーコンテナを保存する必要があることを確認します。
historyPolicyContainerのクローンを返します。
もしresponseURLがabout:srcdocである場合:
もしresponseURLがローカルであり、initiatorPolicyContainerがnullでない場合、initiatorPolicyContainerのクローンを返します。
もしresponsePolicyContainerがnullでない場合、それを返します。
新しいポリシーコンテナを返します。
ワーカーグローバルスコープのポリシーコンテナを初期化するには、WorkerGlobalScopeworkerGlobalScope、レスポンスresponse、および環境environmentを指定します。
それ以外の場合、workerGlobalScopeのポリシーコンテナをresponseとenvironmentを指定してフェッチレスポンスからポリシーコンテナを作成する結果に設定します。
Window, WindowProxy, およびLocationオブジェクト通常、オブジェクトはオリジンをまたいでアクセスすることはできませんが、ウェブプラットフォームが依存しているそのルールに対する一部のレガシー例外が存在しないと、ウェブプラットフォームは本来の姿ではないでしょう。
このセクションでは、JavaScript仕様からの用語と書式設定の慣例を使用しています。[JAVASCRIPT]
セキュリティチェックを実行するがplatformObject、identifier、およびtypeと共に呼び出された場合、次のステップを実行します。
各eに対して、CrossOriginProperties(platformObject)を実行します。
もしSameValue(e.[[Property]], identifier)がtrueであれば、次のステップを実行します。
もしtypeが「method」であり、eが[[NeedsGet]]または[[NeedsSet]]を持っていない場合、終了します。
それ以外で、typeが「getter」であり、e.[[NeedsGet]]がtrueである場合、終了します。
それ以外で、typeが「setter」であり、e.[[NeedsSet]]がtrueである場合、終了します。
もしIsPlatformObjectSameOrigin(platformObject)がfalseであれば、"SecurityError" DOMExceptionをスローします。
WindowおよびLocationオブジェクトには、値が初期状態で空のマップである[[CrossOriginPropertyDescriptorMap]]内部スロットが含まれています。
[[CrossOriginPropertyDescriptorMap]]内部スロットには、currentGlobalがobjectGlobalからWindowまたはLocationオブジェクトを検査するときに、スクリプトに見える内容をメモ化するために、currentGlobal、objectGlobal、およびpropertyKeyをキーとし、プロパティディスクリプタを値とするエントリを持つマップが含まれています。このマップはCrossOriginGetOwnPropertyHelperによって遅延的に埋められ、将来の検索で参照されます。
ユーザーエージェントは、値のいかなる部分にも参照が保持されていないとき、対応するキーと共にマップ内の値をガベージコレクトできるようにする必要があります。つまり、ガベージコレクションが観察可能でない限りです。
例えば、const href = Object.getOwnPropertyDescriptor(crossOriginLocation, "href").setのように、値とそれに対応するキーは、ガベージコレクトすると観察可能になるため、ガベージコレクトできません。
ユーザーエージェントは、document.domainが設定されたときに、マップからキーと値のペアを削除する最適化を持つことができます。これは、document.domainが以前の値に戻ることができないため、観察可能ではありません。
例えば、document.domainをwww.example.comで"example.com"に設定する場合、ユーザーエージェントは、キーの一部がwww.example.comであるすべてのキーと値のペアをマップから削除できます。これは、www.example.comが再びオリジンの一部になることはなく、したがって対応する値がマップから再取得されることはないためです。
もしOがLocationオブジェクトであるならば、以下を返します:
href", [[NeedsGet]]: false, [[NeedsSet]]: true }, { [[Property]]:
"replace" } »
以下を返します:
« { [[Property]]: "window", [[NeedsGet]]: true, [[NeedsSet]]: false }, { [[Property]]:
"self", [[NeedsGet]]: true, [[NeedsSet]]: false }, { [[Property]]: "location",
[[NeedsGet]]: true, [[NeedsSet]]: true }, { [[Property]]: "close" }, { [[Property]]:
"closed", [[NeedsGet]]: true, [[NeedsSet]]: false }, { [[Property]]: "focus" }, {
[[Property]]: "blur" }, { [[Property]]: "frames", [[NeedsGet]]: true,
[[NeedsSet]]: false }, { [[Property]]: "length", [[NeedsGet]]: true, [[NeedsSet]]: false }, {
[[Property]]: "top", [[NeedsGet]]: true, [[NeedsSet]]: false }, { [[Property]]:
"opener", [[NeedsGet]]: true, [[NeedsSet]]: false }, { [[Property]]: "parent",
[[NeedsGet]]: true, [[NeedsSet]]: false }, { [[Property]]: "postMessage" } »
この抽象操作は、Completion Recordを返しません。
インデックス付きプロパティは、このアルゴリズムで安全リストに追加する必要はありません。これらは直接WindowProxyオブジェクトによって処理されます。
JavaScriptのプロパティ名Pが「クロスオリジンアクセス可能なウィンドウプロパティ名」であるためには、それが「window」、「self」、「location」、「close」、「closed」、「focus」、「blur」、「frames」、「length」、「top」、「opener」、「parent」、「postMessage」、または配列インデックスプロパティ名のいずれかである必要があります。
もしPが「then」、%Symbol.toStringTag%、%Symbol.hasInstance%、または%Symbol.isConcatSpreadable%である場合、以下を返します:
"SecurityError" DOMExceptionをスローします。
現在の設定オブジェクトのオリジンがOの関連する設定オブジェクトのオリジンと同一オリジンドメインである場合にtrueを返し、それ以外の場合はfalseを返します。
この抽象操作は、Completion Recordを返しません。
ここでの現在の設定オブジェクトは概ね「呼び出し元」に対応します。このチェックは、対象となるゲッター/セッター/メソッドのための実行コンテキストがJavaScript実行コンテキストスタックに入る前に行われます。例えば、コードw.documentでは、このステップはdocumentゲッターに到達する前に[[Get]]アルゴリズムの一部として呼び出されます。
この抽象操作がundefinedを返し、カスタム動作がない場合、呼び出し元は"SecurityError" DOMExceptionをスローする必要があります。実際には、これは呼び出し元がCrossOriginPropertyFallbackを呼び出すことで処理されます。
crossOriginKeyを、現在の設定オブジェクト、Oの関連する設定オブジェクト、およびPから成るタプルとします。
CrossOriginProperties(O)の各eについて:
もしSameValue(e.[[Property]], P)がtrueである場合、次のステップを実行します:
もしOの[[CrossOriginPropertyDescriptorMap]]内部スロットの値がcrossOriginKeyをキーとするエントリを含む場合、そのエントリの値を返します。
originalDescをOrdinaryGetOwnProperty(O, P)とします。
crossOriginDescをundefinedとします。
もしe.[[NeedsGet]]および[[NeedsSet]]が存在しない場合:
valueをoriginalDesc.[[Value]]とします。
もしIsCallable(value)がtrueである場合、valueを、現在の領域で作成された、O上のIDL操作Pと同じステップを実行する匿名組み込み関数に設定します。
crossOriginDescをPropertyDescriptor{ [[Value]]: value, [[Enumerable]]: false, [[Writable]]: false, [[Configurable]]: true }に設定します。
それ以外の場合:
crossOriginGetをundefinedとします。
もしe.[[NeedsGet]]がtrueである場合、crossOriginGetを、現在の領域で作成され、O上のIDL属性Pのゲッターと同じステップを実行する匿名組み込み関数に設定します。
crossOriginSetをundefinedとします。
もしe.[[NeedsSet]]がtrueである場合、crossOriginSetを、現在の領域で作成され、O上のIDL属性Pのセッターと同じステップを実行する匿名組み込み関数に設定します。
crossOriginDescをPropertyDescriptor{ [[Get]]: crossOriginGet, [[Set]]: crossOriginSet, [[Enumerable]]: false, [[Configurable]]: true }に設定します。
Oの[[CrossOriginPropertyDescriptorMap]]内部スロットの値に、キーcrossOriginKeyと値crossOriginDescを持つエントリを作成します。
crossOriginDescを返します。
undefinedを返します。
この抽象操作はCompletion Recordを返しません。
ここで生成されたプロパティ記述子が設定可能である理由は、JavaScript仕様書で求められる基本内部メソッドの不変条件を維持するためです。特に、プロパティの値がナビゲーションの結果として変更される可能性があるため、そのプロパティは設定可能である必要があります。(ただし、既存のWebコンテンツとの互換性のために、これらの不変条件を維持できないケースについては、tc39/ecma262 issue #672およびこの仕様書の他の部分を参照してください。)[JAVASCRIPT]
プロパティ記述子が列挙可能でない理由は、これが同一オリジンの動作と一致しないにもかかわらず、既存のWebコンテンツとの互換性のためです。詳細はissue #3183を参照してください。
descを? O.[[GetOwnProperty]](P)とします。
Assert: descはundefinedではありません。
もしIsDataDescriptor(desc)がtrueである場合、desc.[[Value]]を返します。
Assert: IsAccessorDescriptor(desc)がtrueであることを確認します。
getterをdesc.[[Get]]とします。
もしgetterがundefinedである場合、"SecurityError" DOMExceptionをスローします。
? Call(getter, Receiver)を返します。
descを? O.[[GetOwnProperty]](P)とします。
Assert: descはundefinedではありません。
もしdesc.[[Set]]が存在し、その値がundefinedでない場合、次を実行します:
? Call(setter, Receiver, « V »)を実行します。
trueを返します。
"SecurityError" DOMExceptionをスローします。
keysを新しい空のリストに設定します。
CrossOriginProperties(O)の各eについて、リストに追加e.[[Property]]をkeysに設定します。
keysの結合を返します: « "then", %Symbol.toStringTag%, %Symbol.hasInstance%, %Symbol.isConcatSpreadable% ».
この抽象操作はCompletion Recordを返しません。
Window objectすべての現在のエンジンでサポートされています。
[Global =Window ,
Exposed =Window ,
LegacyUnenumerableNamedProperties ]
interface Window : EventTarget {
// the current browsing context
[LegacyUnforgeable ] readonly attribute WindowProxy window ;
[Replaceable ] readonly attribute WindowProxy self ;
[LegacyUnforgeable ] readonly attribute Document document ;
attribute DOMString name ;
[PutForwards =href , LegacyUnforgeable ] readonly attribute Location location ;
readonly attribute History history ;
readonly attribute Navigation navigation ;
readonly attribute CustomElementRegistry customElements ;
[Replaceable ] readonly attribute BarProp locationbar ;
[Replaceable ] readonly attribute BarProp menubar ;
[Replaceable ] readonly attribute BarProp personalbar ;
[Replaceable ] readonly attribute BarProp scrollbars ;
[Replaceable ] readonly attribute BarProp statusbar ;
[Replaceable ] readonly attribute BarProp toolbar ;
attribute DOMString status ;
undefined close ();
readonly attribute boolean closed ;
undefined stop ();
undefined focus ();
undefined blur ();
// other browsing contexts
[Replaceable ] readonly attribute WindowProxy frames ;
[Replaceable ] readonly attribute unsigned long length ;
[LegacyUnforgeable ] readonly attribute WindowProxy ? top ;
attribute any opener ;
[Replaceable ] readonly attribute WindowProxy ? parent ;
readonly attribute Element ? frameElement ;
WindowProxy ? open (optional USVString url = "", optional DOMString target = "_blank", optional [LegacyNullToEmptyString ] DOMString features = "");
// Since this is the global object, the IDL named getter adds a NamedPropertiesObject exotic
// object on the prototype chain. Indeed, this does not make the global object an exotic object.
// Indexed access is taken care of by the WindowProxy exotic object.
getter object (DOMString name );
// the user agent
readonly attribute Navigator navigator ;
[Replaceable ] readonly attribute Navigator clientInformation ; // legacy alias of .navigator
readonly attribute boolean originAgentCluster ;
// user prompts
undefined alert ();
undefined alert (DOMString message );
boolean confirm (optional DOMString message = "");
DOMString ? prompt (optional DOMString message = "", optional DOMString default = "");
undefined print ();
undefined postMessage (any message , USVString targetOrigin , optional sequence <object > transfer = []);
undefined postMessage (any message , optional WindowPostMessageOptions options = {});
// also has obsolete members
};
Window includes GlobalEventHandlers ;
Window includes WindowEventHandlers ;
dictionary WindowPostMessageOptions : StructuredSerializeOptions {
USVString targetOrigin = "/";
};
window.window
すべての現在のエンジンでサポートされています。
window.frames
すべての現在のエンジンでサポートされています。
window.self
すべての現在のエンジンでサポートされています。
これらの属性はすべてwindowを返します。
window.document
すべての現在のエンジンでサポートされています。
windowに関連付けられたDocumentを返します。
document.defaultView
すべての現在のエンジンでサポートされています。
documentに関連付けられたWindowを返します。関連付けがない場合はnullを返します。
The Window object has an associated
Document, which is a Document object. It is set when the Window object is created, and only ever changed
during navigation from the initial about:blank Document.
A Window's browsing context is its associated Document's browsing context. It
is either null or a browsing
context.
A Window's navigable is the navigable whose active document is the Window's associated Document's, or null if there is
no such navigable.
The window, frames, and self getter steps are to return
this's relevant
realm.[[GlobalEnv]].[[GlobalThisValue]].
The document getter steps
are to return this's associated Document.
The Document object associated with
a Window object can change in exactly one case:
when the navigate algorithm creates a new
Document object for the first page loaded in a browsing context. In that specific case, the Window object of the initial
about:blank page is reused and gets a new Document object.
The defaultView
getter steps are:
If this's browsing context is null, then return null.
Return this's browsing context's WindowProxy object.
すべての現在のエンジンでサポートされています。
歴史的理由により、Windowオブジェクトには、名前がHTMLDocumentで、値がDocumentのインターフェイスオブジェクトである、書き込み可能で、設定可能で、列挙不可能なプロパティも存在しなければなりません。
window = window.open([ url [, target [, features ] ] ])
すべての現在のエンジンでサポートされています。
urlを表示するためのウィンドウを開き(デフォルトは"about:blank")、それを返します。target(デフォルトは"_blank")は新しいウィンドウの名前を指定します。その名前のウィンドウが既に存在する場合、それが再利用されます。features引数には、コンマ区切りのトークンのセットが含まれることがあります:
noopener"
noreferrer"
これらは、ハイパーリンクのnoopenerおよびnoreferrerリンクタイプと同様に動作します。
popup"
ユーザーエージェントに対し、新しいウィンドウに対して最小限のWebブラウザーインターフェイスを提供することを促します。(すべてのBarPropオブジェクトのvisibleゲッターに影響を与えます。)
globalThis. open( "https://email.example/message/CAOOOkFcWW97r8yg=SsWg7GgCmp4suVX9o85y8BvNRqMjuc5PXg" , undefined , "noopener,popup" );
window.name [ = value ]
すべての現在のエンジンでサポートされています。
ウィンドウの名前を返します。
設定することで、名前を変更できます。
window.close()
すべての現在のエンジンでサポートされています。
ウィンドウを閉じます。
window.closed
すべての現在のエンジンでサポートされています。
ウィンドウが閉じられている場合はtrueを返し、そうでない場合はfalseを返します。
window.stop()
すべての現在のエンジンでサポートされています。
ドキュメントの読み込みをキャンセルします。
ウィンドウを開く手順は、文字列url、文字列target、および文字列featuresを指定して次の手順で実行されます:
イベントループの終了ネスティングレベルがゼロでない場合は、nullを返します。
sourceDocumentを、エントリーグローバルオブジェクトの関連するDocumentとします。
targetが空文字列の場合、targetを"_blank"に設定します。
tokenizedFeaturesを、featuresをトークン化した結果とします。
noopenerおよびnoreferrerをfalseに設定します。
もしtokenizedFeatures["noopener"]が存在する場合、次を実行します:
noopenerを、tokenizedFeatures["noopener"]をブール機能として解析した結果に設定します。
削除
tokenizedFeatures["noopener"]。
もしtokenizedFeatures["noreferrer"]が存在する場合、次を実行します:
noreferrerを、tokenizedFeatures["noreferrer"]をブール機能として解析した結果に設定します。
削除
tokenizedFeatures["noreferrer"]。
referrerPolicyを空文字列に設定します。
もしnoreferrerがtrueの場合、noopenerをtrueに設定し、referrerPolicyを"no-referrer"に設定します。
targetNavigableとwindowTypeを、ナビゲーションの選択ルールを適用した結果として設定します。
リンクをコントロールクリックして新しいタブで開くことをサポートしているユーザーエージェントが存在し、onclickハンドラがwindow.open()APIを使用してiframe要素にページを開く場合、ユーザーエージェントはターゲットブラウジングコンテキストの選択を無視し、代わりに新しいタブをターゲットにすることができます。
もしtargetNavigableがnullの場合、nullを返します。
もしwindowTypeが"new and unrestricted"または"new with no opener"のいずれかである場合、次を実行します:
targetNavigableのアクティブなブラウジングコンテキストのポップアップであるかどうかを、ポップアップウィンドウが要求されているかどうかをチェックした結果に設定します。
ブラウジングコンテキスト機能を設定し、targetNavigableのアクティブなブラウジングコンテキストに、tokenizedFeaturesに基づいて適用します。[CSSOMVIEW]
urlRecordをURLレコードに設定し、about:blankに設定します。
もしurlが空文字列でない場合、urlRecordをURLのエンコードと解析の結果として設定し、urlに基づいてentry-settings-objectを相対的に設定します。
もしurlRecordが失敗した場合、"SyntaxError" DOMExceptionをスローします。
もしurlRecordがabout:blankに一致する場合、targetNavigableのアクティブなドキュメントとurlRecordに対してURLと履歴の更新手順を実行します。
これはurlがabout:blank?fooのようなものである場合に必要です。もしurlが単なるabout:blankであれば、これは何も行いません。
それ以外の場合、ナビゲートし、targetNavigableをurlRecordに対してsourceDocumentを使用し、referrerPolicyをreferrerPolicyに設定し、exceptionsEnabledをtrueに設定します。
それ以外の場合:
もしurlが空文字列でない場合、次を実行します:
urlRecordをURLのエンコードと解析の結果として設定し、urlに基づいてentry-settings-objectを相対的に設定します。
もしurlRecordが失敗した場合、"SyntaxError" DOMExceptionをスローします。
ナビゲートし、targetNavigableをurlRecordに対してsourceDocumentを使用し、referrerPolicyをreferrerPolicyに設定し、exceptionsEnabledをtrueに設定します。
もしnoopenerがfalseの場合、targetNavigableのアクティブなブラウジングコンテキストのオープナーブラウジングコンテキストをsourceDocumentのブラウジングコンテキストに設定します。
もしnoopenerがtrueまたはwindowTypeが"new with no opener"である場合、nullを返します。
targetNavigableのアクティブなWindowProxyを返します。
open(url, target, features)メソッドの手順は、ウィンドウを開く手順をurl、target、およびfeaturesと共に実行します。
このメソッドは、既存のブラウジングコンテキストをナビゲートするか、補助ブラウジングコンテキストを開いてナビゲートするためのメカニズムを提供します。
features引数をトークン化するには:
tokenizedFeaturesを順序付きマップとして新規作成します。
positionをfeaturesの最初のコードポイントに設定します。
次のpositionがfeaturesの末尾を超えていない間:
nameを空文字列に設定します。
valueを空文字列に設定します。
コードポイントのシーケンスを収集し、featuresからpositionに基づいて機能セパレーターを設定します。これにより、名前の前にある先頭のセパレーターがスキップされます。
コードポイントのシーケンスを収集し、featuresからpositionに基づいて機能セパレーターでないものを収集します。収集された文字をnameに設定し、ASCII小文字に変換します。
nameを機能名を正規化の結果として設定します。
次のpositionがfeaturesの末尾を超えておらず、featuresのpositionにあるコードポイントがU+003D (=)でない間:
もしfeaturesのpositionにあるコードポイントがU+002C (,)である場合、または機能セパレーターでない場合、ブレイクします。
positionを1進めます。
これにより、最初のU+003D (=)までスキップされますが、U+002C (,)または非セパレーターを超えません。
もしfeaturesのpositionにあるコードポイントが機能セパレーターである場合:
positionがfeaturesの末尾を超えておらず、featuresのpositionにあるコードポイントが機能セパレーターである間:
もしfeaturesのpositionにあるコードポイントがU+002C (,)である場合、ブレイクします。
positionを1進めます。
これにより、最初の非セパレーターまでスキップされますが、U+002C (,)を超えません。
コードポイントのシーケンスを収集し、featuresからpositionに基づいて機能セパレーターでないコードポイントを収集します。収集されたコードポイントをvalueに設定し、ASCII小文字に変換します。
もしnameが空文字列でない場合、tokenizedFeatures[name]をvalueに設定します。
tokenizedFeaturesを返します。
ウィンドウ機能が設定されているかどうかを確認するには、tokenizedFeatures、featureName、およびdefaultValueを指定して次の手順で実行します:
もしtokenizedFeatures[featureName]が存在する場合、tokenizedFeatures[featureName]をブール機能として解析した結果を返します。
defaultValueを返します。
ポップアップウィンドウが要求されているかどうかを確認するには、tokenizedFeaturesを指定して次の手順で実行します:
もしtokenizedFeaturesが空の場合、falseを返します。
もしtokenizedFeatures["popup"]が存在する場合、tokenizedFeatures["popup"]をブール機能として解析した結果を返します。
locationを、ウィンドウ機能が設定されているかどうかを確認した結果とし、tokenizedFeatures、"location"、およびfalseを使用して確認します。
toolbarを、ウィンドウ機能が設定されているかどうかを確認した結果とし、tokenizedFeatures、"toolbar"、およびfalseを使用して確認します。
もしlocationとtoolbarの両方がfalseの場合、trueを返します。
menubarを、ウィンドウ機能が設定されているかどうかを確認した結果とし、tokenizedFeatures、"menubar"、およびfalseを使用して確認します。
もしmenubarがfalseの場合、trueを返します。
resizableを、ウィンドウ機能が設定されているかどうかを確認した結果とし、tokenizedFeatures、"resizable"、およびtrueを使用して確認します。
もしresizableがfalseの場合、trueを返します。
scrollbarsを、ウィンドウ機能が設定されているかどうかを確認した結果とし、tokenizedFeatures、"scrollbars"、およびfalseを使用して確認します。
もしscrollbarsがfalseの場合、trueを返します。
statusを、ウィンドウ機能が設定されているかどうかを確認した結果とし、tokenizedFeatures、"status"、およびfalseを使用して確認します。
もしstatusがfalseの場合、trueを返します。
falseを返します。
コードポイントがフィーチャーセパレーターである場合、それがASCIIホワイトスペース、U+003D(=)、またはU+002C(,)である。
レガシーの理由により、一部の機能名にはいくつかの別名があります。nameを指定して機能名を正規化するには、nameに応じて切り替えます:
screenx"
left"を返します。
screeny"
top"を返します。
innerwidth"
width"を返します。
innerheight"
height"を返します。
valueを指定して、ブール機能を解析するには:
もしvalueが空文字列である場合、trueを返します。
もしvalueが"yes"である場合、trueを返します。
もしvalueが"true"である場合、trueを返します。
parsedを、整数として解析した結果として設定します。
もしparsedがエラーの場合、それを0に設定します。
もしparsedが0である場合、falseを返します。それ以外の場合はtrueを返します。
namegetterの手順は、次のとおりです:
name
setterの手順は、次のとおりです:
thisのナビゲーブルのアクティブなセッション履歴エントリのドキュメント状態のナビゲーブルターゲット名を指定された値に設定します。
ナビゲーブルが別のオリジンにナビゲートされたとき、名前はリセットされます。
close()メソッドの手順は、次のとおりです:
もしthisTraversableがトップレベルのトラバーサブルでない場合、終了します。
もしthisTraversableのクローズ中がtrueである場合、終了します。
browsingContextをthisTraversableのアクティブなブラウジングコンテキストに設定します。
sourceSnapshotParamsを、スナップショットのソーススナップショットパラメーターのスナップショットとして設定し、thisTraversableのアクティブなドキュメントを指定して実行します。
次のすべてがtrueである場合:
thisTraversableがスクリプトでクローズ可能である;
現任のグローバルオブジェクトのブラウジングコンテキストがbrowsingContextと親しい;
現任のグローバルオブジェクトのナビゲーブルがsourceSnapshotParamsを指定してthisTraversableをナビゲートすることがサンドボックスによって許可されている;
次の手順を実行します:
thisTraversableのクローズ中をtrueに設定します。
タスクをキューに入れ、DOM操作タスクソースに対して、thisTraversableを閉じるように指示します。
ナビゲーブルは、アクティブなブラウジングコンテキストがスクリプトによって作成された補助ブラウジングコンテキストであるか、トップレベルのトラバーサブルで、そのセッション履歴エントリのサイズが1の場合、スクリプトでクローズ可能です。
closedgetterの手順は、thisのブラウジングコンテキストがnullであるか、クローズ中がtrueである場合、trueを返します。それ以外の場合はfalseを返します。
stop()メソッドの手順は、次のとおりです:
Windowオブジェクトにおけるインデックスアクセスwindow.length
すべての現在のエンジンでサポートされています。
ドキュメントツリーの子ナビゲーブルの数を返します。
window[index]
指定されたドキュメントツリーの子ナビゲーブルに対応するWindowProxyを返します。
lengthgetterの手順は、次のとおりです:
thisの関連付けられたDocumentのドキュメントツリーの子ナビゲーブルのサイズを返します。
ドキュメントツリーの子ナビゲーブルへのインデックスアクセスは、WindowProxyオブジェクトの[[GetOwnProperty]]内部メソッドによって定義されています。
Window オブジェクトでの名前付きアクセスwindow[name]
指定された要素または要素のコレクションを返します。
一般的に、これに依存すると脆弱なコードにつながる可能性があります。Webプラットフォームに新機能が追加されると、このAPIにマッピングされるIDが時間とともに変わる可能性があります。代わりに、document.getElementById()またはdocument.querySelector()を使用してください。
Window オブジェクト
window のドキュメントツリー子ナビゲーブルターゲット名プロパティセットは、次の手順を実行することで返されます。
children を window の 関連付けられた Document の ドキュメントツリー子ナビゲーブル に設定します。
firstNamedChildren を空の 順序付きセット に設定します。
各 children の navigable について、次の操作を行います。
names を空の 順序付きセット に設定します。
各 firstNamedChildren の navigable について、次の操作を行います。
name を navigable の ターゲット名 に設定します。
navigable の アクティブドキュメント の オリジン が、window の 関連設定オブジェクト の オリジン と同じオリジンである場合、 name を names に追加します。
names を返します。
2つの個別の反復により、次の例では、https://example.org/ でホストされているとして、
https://elsewhere.example/ が window.name に "spices" を設定した場合、すべてが読み込まれた後に
window.spices を評価すると、未定義が返されます:
< iframe src = https://elsewhere.example.com/ ></ iframe >
< iframe name = spices ></ iframe >
Window オブジェクトは名前付きプロパティをサポートします。Window オブジェクト
window のサポートされているプロパティ名は、要素によって提供された順に、重複を無視して、ツリー順で次のように構成されます:
window の ドキュメントツリー子ナビゲーブルターゲット名プロパティセット;
name コンテンツ属性の値で、embed、form、img、および object 要素があり、
非空の name コンテンツ属性を持ち、window の 関連付けられた Document を
ルート として持つドキュメントツリー内に存在するもの;
id
コンテンツ属性の値で、
window の 関連付けられた Document を
ルート として持つドキュメントツリー内に存在する、非空の id
コンテンツ属性を持つすべての HTML要素;
名前付きプロパティの値を決定する には、Window オブジェクト window
で次の手順を実行する必要があります。
objects を、名前が name の window の 名前付きオブジェクト のリストに設定します。
このアルゴリズムが Web IDL によって呼び出されない のであれば、そのようなオブジェクトが少なくとも1つは存在します。
objects に ナビゲーブル が含まれている場合は、次の操作を行います。
container を、window の 関連付けられた
Document の 子孫 の中で、
objects に コンテンツナビゲーブル が含まれている最初の ナビゲーブルコンテナ に設定します。
container の コンテンツナビゲーブル の アクティブな WindowProxy を返します。
それ以外の場合、objects に要素が1つしかない場合は、その要素を返します。
それ以外の場合、window の 関連付けられた Document
をルートとし、そのフィルタが window の名前が name の 名前付きオブジェクト のみを一致させる HTMLCollection
を返します。(定義により、これらはすべて要素になります。)
名前付きオブジェクトは、Window オブジェクト window の名前
name の、上記のアルゴリズムの目的のための次のものを含みます:
ドキュメントツリー子ナビゲーブル
は、window の 関連付けられた Document
における
ターゲット名 が name のもの;
embed、
form、
img、または
object
要素が、name の name コンテンツ属性を持ち、
window の 関連付けられた Document を
ルート として持つドキュメントツリー内に存在するもの;
HTML要素 は、
window の 関連付けられた Document を
ルート として持つドキュメントツリー内に存在する、name の値を持つ id
コンテンツ属性を持つもの;
Window
インターフェイスには、[Global] 拡張属性があるため、その名前付きプロパティは、
名前付きプロパティオブジェクト の規則に従い、
レガシープラットフォームオブジェクト の規則には従いません。
window.top
すべての現在のエンジンでサポートされています。
最上位のトラバーサブルのためのWindowProxyを返します。
window.opener [ = value ]
すべての現在のエンジンでサポートされています。
opener ブラウジングコンテキストのためのWindowProxyを返します。
存在しない場合、または null に設定されている場合は null を返します。
null に設定することができます。
window.parent
すべての現在のエンジンでサポートされています。
親ナビゲーブルのためのWindowProxyを返します。
window.frameElement
すべての現在のエンジンでサポートされています。
ナビゲーブルコンテナ要素を返します。
存在しない場合、およびクロスオリジンの状況では null を返します。
topの getter 手順は以下の通りです:
openerの getter 手順は以下の通りです:
current をthisのブラウジングコンテキストとします。
もしcurrent が null であれば、null を返します。
もしcurrent のopener ブラウジングコンテキスト が null であれば、null を返します。
current のopener ブラウジングコンテキストのWindowProxyオブジェクトを返します。
openerの setter 手順は以下の通りです:
指定された値が null であり、thisのブラウジングコンテキストが null でない場合、thisのブラウジングコンテキストのopener ブラウジングコンテキストを null に設定します。
指定された値が null でない場合、DefinePropertyOrThrow(this, "opener", {
[[Value]]: 指定された値, [[Writable]]: true, [[Enumerable]]: true, [[Configurable]]: true
})を実行します。
window.opener を null に設定すると、opener
ブラウジングコンテキストの参照がクリアされます。実際には、これにより将来のスクリプトが自身のopener
ブラウジングコンテキストのWindowオブジェクトにアクセスできなくなります。
デフォルトでは、スクリプトは自身のopener
ブラウジングコンテキストのWindowオブジェクトにアクセスできます。例えば、スクリプトはwindow.opener.locationを設定し、opener
ブラウジングコンテキストをナビゲートさせることができます。
parentの getter 手順は以下の通りです:
もしnavigable が null であれば、null を返します。
navigable のアクティブなWindowProxyを返します。
frameElementの getter 手順は以下の通りです:
もしcurrent が null であれば、null を返します。
container をcurrentのコンテナとします。
もしcontainer が null であれば、null を返します。
もしcontainer のノードドキュメントのオリジンが同一オリジンドメインと一致しない場合、null を返します。
container を返します。
これらのプロパティが null を返す場合の例は次のとおりです:
<!DOCTYPE html>
< iframe ></ iframe >
< script >
"use strict" ;
const element = document. querySelector( "iframe" );
const iframeWindow = element. contentWindow;
element. remove();
console. assert( iframeWindow. top === null );
console. assert( iframeWindow. parent === null );
console. assert( iframeWindow. frameElement === null );
</ script >
ここで、iframeWindowに対応するブラウジングコンテキストは、elementがドキュメントから削除されたときにnulled
outされました。
歴史的な理由から、Window
インターフェースには、特定のウェブブラウザーインターフェース要素の可視性を表すプロパティが含まれていました。
プライバシーと互換性の理由から、これらのプロパティは現在、
Windowの
ブラウジングコンテキストの
is popupプロパティが真であるか
偽であるかを表す値を返します。
各インターフェース要素はBarPropオブジェクトで表されます:
すべての現在のエンジンでサポートされています。
[Exposed =Window ]
interface BarProp {
readonly attribute boolean visible ;
};
window.locationbar.visible
すべての現在のエンジンでサポートされています。
window.menubar.visible
すべての現在のエンジンでサポートされています。
window.personalbar.visible
すべての現在のエンジンでサポートされています。
window.scrollbars.visible
すべての現在のエンジンでサポートされています。
window.statusbar.visible
すべての現在のエンジンでサポートされています。
window.toolbar.visible
すべての現在のエンジンでサポートされています。
Windowがポップアップでない場合は true
を返し、それ以外の場合は false を返します。
すべての現在のエンジンでサポートされています。
visible
ゲッターの手順は次のとおりです:
browsingContext を this の 関連するグローバルオブジェクト の ブラウジングコンテキスト に設定します。
browsingContext が null である場合、true を返します。
browsingContext の トップレベルブラウジングコンテキスト の ポップアップ であるかどうかの否定を返します。
次の BarProp オブジェクトは、各 Window オブジェクトに対して存在する必要があります:
BarProp オブジェクト
BarProp オブジェクト
BarProp オブジェクト
BarProp オブジェクト
BarProp オブジェクト
BarProp オブジェクト
locationbar 属性は、ロケーションバー
BarProp オブジェクト を返す必要があります。
menubar 属性は、メニューバー
BarProp オブジェクト を返す必要があります。
personalbar 属性は、パーソナルバー
BarProp オブジェクト を返す必要があります。
scrollbars 属性は、スクロールバー
BarProp オブジェクト を返す必要があります。
statusbar 属性は、ステータスバー
BarProp オブジェクト を返す必要があります。
toolbar 属性は、ツールバー
BarProp オブジェクト を返す必要があります。
歴史的な理由から、status
属性は、Window
オブジェクトで、取得時には設定された最後の文字列を返し、設定時には新しい値に設定されます。Window
オブジェクトが作成されると、属性は空文字列に設定される必要があります。それ以外のことは行いません。
Window オブジェクトのスクリプト設定ウィンドウ環境設定オブジェクトを設定するために、URL creationURL、JavaScript実行コンテキスト execution context、nullまたは環境 reservedEnvironment、URL topLevelCreationURL、およびオリジン topLevelOriginが与えられた場合、次の手順を実行します。
realm を execution context の Realm コンポーネントの値に設定します。
window を realm の グローバルオブジェクト に設定します。
settings object を新しい環境設定オブジェクトに設定し、そのアルゴリズムを次のように定義します。
execution context を返します。
次の2つの条件を満たす場合は true を、それ以外の場合は false を返します。
realm のエージェントクラスタのクロスオリジン孤立モードが
"concrete"
であること。
window に関連付けられた Document
の読み込みタイミング情報のナビゲーション開始時間を返します。
もし reservedEnvironment が null でない場合は、次の手順を実行します。
settings object のid を reservedEnvironment のid に設定し、ターゲットブラウジングコンテキストを reservedEnvironment のターゲットブラウジングコンテキストに設定し、アクティブサービスワーカーを reservedEnvironment のアクティブサービスワーカーに設定します。
reservedEnvironment のid を空の文字列に設定します。
予約された環境の識別情報は、作成された環境設定オブジェクトに完全に転送されたと見なされます。この時点から、予約された環境はそのidによって検索されることはありません。
それ以外の場合は、settings object のid を新しい一意の不透明な文字列に設定し、settings object のターゲットブラウジングコンテキストを null に設定し、settings object のアクティブサービスワーカーを null に設定します。
settings object の作成URL を creationURL に設定し、settings object の最上位作成URL を topLevelCreationURL に設定し、settings object の最上位オリジン を topLevelOrigin に設定します。
realm の [[HostDefined]] フィールドを settings object に設定します。
WindowProxy エキゾチックオブジェクトWindowProxy は、Window
通常オブジェクトをラップするエキゾチックオブジェクトであり、ほとんどの操作をラップされたオブジェクトに間接的に行います。各ブラウジングコンテキストには、関連付けられたWindowProxyオブジェクトがあります。ブラウジングコンテキストがナビゲートされると、ブラウジングコンテキストに関連付けられたWindowProxyオブジェクトによってラップされているWindowオブジェクトが変更されます。
WindowProxyエキゾチックオブジェクトは、以下で明示的に指定されている場合を除き、通常の内部メソッドを使用しなければなりません。
WindowProxyインターフェースオブジェクトは存在しません。
すべてのWindowProxyオブジェクトには、ラップされたWindowオブジェクトを表す[[Window]]内部スロットがあります。
WindowProxyは「プロキシ」と名付けられていますが、実際のプロキシのようにターゲットの内部メソッドで多態性ディスパッチを行うことはありません。これは、WindowProxyオブジェクトとLocationオブジェクトの間でメカニズムを再利用するためです。Windowオブジェクトが通常オブジェクトである限り、これは観測不可能であり、どちらの方法でも実装できます。
W を、this の [[Window]] 内部スロットの値とする。
IsPlatformObjectSameOrigin(W) が true である場合、! OrdinaryGetPrototypeOf(W) を返す。
null を返す。
! SetImmutablePrototype(this, V) を返す。
true を返す。
false を返す。
W を、this の [[Window]] 内部スロットの値とする。
P が 配列インデックスプロパティ名 である場合、以下を行う。
index を ! ToUint32(P) とする。
children を、W の関連するDocument の ドキュメントツリーの子ナビゲーブル とする。
value を undefined とする。
index が children の サイズ 未満である場合、以下を行う。
children を昇順にソートし、navigableA が navigableB
よりも小さいと見なす。navigableA の コンテナ が、navigableB の コンテナ よりも先に
W の 関連するDocument
に挿入された場合。
value を children[index] の アクティブなWindowProxy に設定する。
value が undefined の場合、以下を行う。
IsPlatformObjectSameOrigin(W) が true である場合、undefined を返す。
"SecurityError" DOMException
をスローする。
PropertyDescriptor{ [[Value]]: value, [[Writable]]: false, [[Enumerable]]: true, [[Configurable]]: true } を返す。
IsPlatformObjectSameOrigin(W) が true である場合、! OrdinaryGetOwnProperty(W, P) を返す。
これは、既存のウェブコンテンツとの互換性を維持するために、JavaScript 仕様の意図的な違反です。詳細については、tc39/ecma262 issue #672 を参照してください。[JAVASCRIPT]
property を、CrossOriginGetOwnPropertyHelper(W, P) とする。
property が undefined でない場合、それを返す。
property が undefined であり、P が W のドキュメントツリーの子ナビゲーブルターゲット名プロパティセットに存在する場合、以下を行う。
value を、P の名前を持つ W の名前付きオブジェクト のアクティブなWindowProxy に設定する。
PropertyDescriptor{ [[Value]]: value, [[Enumerable]]: false, [[Writable]]: false, [[Configurable]]: true } を返す。
プロパティディスクリプタが列挙可能でない理由は、既存のウェブコンテンツとの互換性のためです。この点については、issue #3183 を参照してください。
? CrossOriginPropertyFallback(P) を返す。
W を、this の [[Window]] 内部スロットの値とする。
IsPlatformObjectSameOrigin(W) が true である場合、以下を行う。
P が 配列インデックスプロパティ名 である場合、false を返す。
? OrdinaryDefineOwnProperty(W, P, Desc) を返す。
これは、既存のウェブコンテンツとの互換性を維持するために、JavaScript 仕様の意図的な違反です。詳細については、tc39/ecma262 issue #672 を参照してください。[JAVASCRIPT]
"SecurityError" DOMException
をスローする。
W を、this の [[Window]] 内部スロットの値とする。
2つのブラウジングコンテキスト間のアクセスを報告する必要があるかを確認する、現在のグローバルオブジェクトのブラウジングコンテキスト、W のブラウジングコンテキスト、P、および 現在の設定オブジェクト を指定して。
IsPlatformObjectSameOrigin(W) が true である場合、? OrdinaryGet(this, P, Receiver) を返す。
? CrossOriginGet(this, P, Receiver) を返す。
this が渡されるのは、W ではなく、OrdinaryGet とCrossOriginGet が [[GetOwnProperty]] 内部メソッドを呼び出すためです。
W を、this の [[Window]] 内部スロットの値とする。
2つのブラウジングコンテキスト間のアクセスを報告する必要があるかを確認する、現在のグローバルオブジェクトのブラウジングコンテキスト、W のブラウジングコンテキスト、P、および 現在の設定オブジェクト を指定して。
IsPlatformObjectSameOrigin(W) が true である場合、以下を行う。
P が 配列インデックスプロパティ名 である場合、false を返す。
? OrdinarySet(W, P, V, Receiver) を返す。
? CrossOriginSet(this, P, V, Receiver) を返す。
this が渡されるのは、W ではなく、CrossOriginSet が [[GetOwnProperty]] 内部メソッドを呼び出すためです。
W を、this の [[Window]] 内部スロットの値とする。
IsPlatformObjectSameOrigin(W) が true である場合、以下を行う。
P が 配列インデックスプロパティ名 である場合、以下を行う。
desc を ! this.[[GetOwnProperty]](P) に設定する。
desc が未定義である場合、true を返す。
false を返す。
? OrdinaryDelete(W, P) を返す。
"SecurityError" DOMException
をスローする。
W を、this の [[Window]] 内部スロットの値とする。
maxProperties を、W の関連付けられたDocumentの文書ツリーの子ナビゲーブルのサイズとする。
keys を排他的範囲 0 から maxProperties まで(maxProperties を除く)の範囲に設定する。
IsPlatformObjectSameOrigin(W) が true である場合、keys と OrdinaryOwnPropertyKeys(W) を連結して返す。
keys と ! CrossOriginOwnPropertyKeys(W) を連結して返す。
Location インターフェースすべての現行エンジンでサポートされています。
すべての現行エンジンでサポートされています。
すべての現行エンジンでサポートされています。
各 Window オブジェクトには、そのオブジェクトが作成されるときに割り当てられる
Location オブジェクトの一意のインスタンスが関連付けられます。
Location エキゾチックオブジェクトは、IDL
の寄せ集め、作成後の JavaScript 内部メソッドの呼び出し、および JavaScript 内部メソッドのオーバーライドを通じて定義されています。その厳しいセキュリティ
ポリシーと相まって、このような奇怪なオブジェクトを実装する際には、特に注意を払ってください。
Location オブジェクトを作成するには、次の手順を実行します。
location を新しい Location
プラットフォームオブジェクト にします。
valueOf を location の 関連する realm の [[Intrinsics]] に設定します。[[%Object.prototype.valueOf%]]。
! location.[[DefineOwnProperty]]("valueOf", { [[Value]]: valueOf,
[[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: false }) を実行します。
! location.[[DefineOwnProperty]](%Symbol.toPrimitive%, { [[Value]]: undefined, [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: false }) を実行します。
[[DefaultProperties]] 内部スロットの値を location の [[OwnPropertyKeys]]() に設定します。
location を返します。
valueOf と %Symbol.toPrimitive% の独自データ プロパティの追加、およびすべての Location の IDL 属性が
[LegacyUnforgeable]
としてマークされているという事実は、Location インターフェースを参照するレガシー コードが必要とするものです。または、それを文字列化して、ドキュメント URL
を決定し、それをセキュリティ上重要な方法で使用するためです。特に、valueOf、%Symbol.toPrimitive%、および
[LegacyUnforgeable]
の文字列化対策により、foo[location] = bar や location + "" などのコードが誤って誘導されないようにしています。
document.location [ = value ]
window.location [ = value ]
現在のページの場所を持つ Location
オブジェクトを返します。
別のページに移動するために設定できます。
Document オブジェクトの location ゲッターの手順は、次のとおりです。this の 関連するグローバルオブジェクト の Location オブジェクトを返します。this が
完全にアクティブ である場合、そうでない場合は null を返します。
Window オブジェクトの location ゲッター手順は、次のとおりです。this の
Location オブジェクトを返します。
Location オブジェクトは、関連する Document の URL の表現と、関連するナビゲーション および再読み込みのメソッドを提供します。
[Exposed =Window ]
interface Location { // but see also additional creation steps and overridden internal methods
[LegacyUnforgeable ] stringifier attribute USVString href ;
[LegacyUnforgeable ] readonly attribute USVString origin ;
[LegacyUnforgeable ] attribute USVString protocol ;
[LegacyUnforgeable ] attribute USVString host ;
[LegacyUnforgeable ] attribute USVString hostname ;
[LegacyUnforgeable ] attribute USVString port ;
[LegacyUnforgeable ] attribute USVString pathname ;
[LegacyUnforgeable ] attribute USVString search ;
[LegacyUnforgeable ] attribute USVString hash ;
[LegacyUnforgeable ] undefined assign (USVString url );
[LegacyUnforgeable ] undefined replace (USVString url );
[LegacyUnforgeable ] undefined reload ();
[LegacyUnforgeable , SameObject ] readonly attribute DOMStringList ancestorOrigins ;
};
location.toString()
location.href
すべての現行エンジンでサポートされています。
すべての現行エンジンでサポートされています。
Location オブジェクトの URL を返します。
設定すると、指定された URL へナビゲートします。
location.origin
すべての現行エンジンでサポートされています。
Location オブジェクトの URL のオリジンを返します。
location.protocol
すべての現行エンジンでサポートされています。
Location オブジェクトの URL のスキームを返します。
設定すると、スキームが変更された同じ URL へナビゲートします。
location.host
すべての現行エンジンでサポートされています。
Location オブジェクトの URL のホストおよびポート
(スキームのデフォルト ポートとは異なる場合)。
設定すると、ホストおよびポートが変更された同じ URL へナビゲートします。
location.hostname
すべての現行エンジンでサポートされています。
Location オブジェクトの URL のホストを返します。
設定すると、ホストが変更された同じ URL へナビゲートします。
location.port
すべての現行エンジンでサポートされています。
Location オブジェクトの URL のポートを返します。
設定すると、ポートが変更された同じ URL へナビゲートします。
location.pathname
すべての現行エンジンでサポートされています。
Location オブジェクトの URL のパスを返します。
設定すると、パスが変更された同じ URL へナビゲートします。
location.search
すべての現行エンジンでサポートされています。
Location オブジェクトの URL のクエリ
(非空の場合、先頭の「?」を含む) を返します。
設定すると、クエリが変更された同じ URL へナビゲートします (先頭の「?」は無視されます)。
location.hash
すべての現行エンジンでサポートされています。
Location オブジェクトの URL のフラグメント
(非空の場合、先頭の「#」を含む) を返します。
設定すると、フラグメントが変更された同じ URL へナビゲートします (先頭の「#」は無視されます)。
location.assign(url)
すべての現行エンジンでサポートされています。
指定された URL へナビゲートします。
location.replace(url)
すべての現行エンジンでサポートされています。
現在のページをセッション履歴から削除し、指定された URL へナビゲートします。
location.reload()
すべての現行エンジンでサポートされています。
現在のページを再読み込みします。
location.ancestorOrigins
DOMStringList
オブジェクトを返します。これは、祖先ナビゲーブルの
アクティブ ドキュメントのオリジンをリストします。
Location オブジェクトには関連付けられた 関連する Document があり、これはこの Location オブジェクトの 関連するグローバルオブジェクト の ブラウジングコンテキスト の アクティブドキュメント であり、このオブジェクトの 関連するグローバルオブジェクト の browsing context が null でない場合に適用されます。そうでない場合は null です。
Location オブジェクトには関連付けられた URL があり、これはこの Location オブジェクトの 関連する Document の URL であり、この Location オブジェクトの 関連する Document が null
でない場合に適用されます。そうでない場合は about:blank
です。
Location オブジェクトには関連付けられた 祖先オリジンリスト があり、Location オブジェクトが作成されたとき、その 祖先オリジンリスト は次の手順によって生成される文字列の リスト に基づく
DOMStringList オブジェクトに設定されます。
output を新しい文字列の リスト として設定します。
current を Location
オブジェクトの 関連する
Document として設定します。
current の コンテナドキュメント が null でない限り次を実行します。
current を current の コンテナドキュメント に設定します。
current の オリジン の シリアライゼーション を output に 追加 します。
output を返します。
Location オブジェクト location を
URL
url にナビゲートするには、オプションで NavigationHistoryBehavior
historyHandling (デフォルトは "auto")
を指定して次の手順を実行します。
navigable を location の 関連するグローバルオブジェクト の ナビゲーブル として設定します。
sourceDocument を 現職グローバルオブジェクト の 関連する
Document として設定します。
location の 関連する
Document がまだ 完全にロードされていない 場合、および 現職グローバルオブジェクト が 一時的なアクティベーション
を持たない場合は、historyHandling を "replace"
に設定します。
sourceDocument を使用して navigable を url に ナビゲート し、exceptionsEnabled を true に設定し、historyHandling を historyHandling に設定します。
href
セッターには意図的にセキュリティチェックがありません。
origin
ゲッターステップは次のとおりです。
this の 関連する Document が null でなく、その origin が same-origin-domain と一致しない場合、"SecurityError" DOMException
をスローします。
シリアライゼーション を返します。
protocol
ゲッターステップは次のとおりです。
this の 関連する Document が null でなく、その origin が same-origin-domain と一致しない場合、"SecurityError" DOMException
をスローします。
protocol
セッターステップは次のとおりです。
this の 関連する Document が null である場合は、何も行いません。
this の 関連する Document の origin が same-origin-domain と一致しない場合、"SecurityError" DOMException
をスローします。
基本的なURL解析 の結果を、copyURL として url
として、与えられた値に続けて ":" とし、スキーム開始状態
を 状態オーバーライド として設定します。
URLパーサは複数の連続するコロンを無視するため、"https:"(または "https::::")
の値を提供することは、"https" の値を提供することと同じです。
possibleFailure が失敗した場合、"SyntaxError" DOMException
をスローします。
copyURL の スキーム が HTTP(S)スキーム でない場合、これらのステップを終了します。
Location-object navigate this を copyURL にナビゲートします。
host
ゲッターステップは次のとおりです。
this の 関連する Document が null でなく、その origin が same origin-domain と一致しない場合、"SecurityError" DOMException
をスローします。
url の host が null の場合、空文字列を返します。
url の host を シリアライズして 返し、それに
":" と url の port を シリアライズして
追加します。
host セッターステップは次のとおりです。
this の 関連する Document が null の場合、何も行いません。
this の 関連する Document の origin が same origin-domain と一致しない場合、"SecurityError" DOMException
をスローします。
copyURL に 不透明なパス がある場合、何も行いません。
与えられた値に対して、copyURL を 基本的な URL 解析 し、copyURL を url とし、host state を state override として設定します。
Location-object navigate this を copyURL にナビゲートします。
hostname
ゲッターステップは次のとおりです。
this の 関連する Document が null でなく、その origin が same origin-domain と一致しない場合、"SecurityError" DOMException
をスローします。
hostname
セッターステップは次のとおりです。
this の 関連する Document が null の場合、何も行いません。
this の 関連する Document の origin が same origin-domain と一致しない場合、"SecurityError" DOMException
をスローします。
copyURL に 不透明なパス がある場合、何も行いません。
与えられた値に対して、copyURL を 基本的な URL 解析 し、copyURL を url とし、hostname state を state override として設定します。
Location-object navigate this を copyURL にナビゲートします。
port
ゲッターステップは次のとおりです。
this の 関連する Document が null でなく、その origin が same origin-domain と一致しない場合、"SecurityError" DOMException
をスローします。
port セッターステップは次のとおりです。
this の 関連する Document が null の場合、何も行いません。
this の 関連する Document の origin が same origin-domain と一致しない場合、"SecurityError" DOMException
をスローします。
copyURL が ユーザー名、パスワード、ポートを持つことができない場合、何も行いません。
与えられた値が空文字列である場合、copyURL の port を null に設定します。
それ以外の場合、基本的な URL 解析 を行い、copyURL を url とし、port state を state override として設定します。
Location-object navigate this を copyURL にナビゲートします。
pathname
ゲッターステップは次のとおりです。
this の 関連する Document が null でなく、その origin が same origin-domain と一致しない場合、"SecurityError" DOMException
をスローします。
この Location オブジェクトの url を URL パスのシリアライズを行った結果 を返します。
pathname
セッターステップは次のとおりです。
this の 関連する Document が null の場合、何も行いません。
this の 関連する Document の origin が same origin-domain と一致しない場合、"SecurityError" DOMException
をスローします。
copyURL に 不透明なパス がある場合、何も行いません。
copyURL の path を空リストに設定します。
与えられた値に対して、copyURL を 基本的な URL 解析 し、copyURL を url とし、path start state を state override として設定します。
Location-object navigate this を copyURL にナビゲートします。
search
ゲッターステップは次のとおりです。
this の 関連する Document が null でなく、その origin が same origin-domain と一致しない場合、"SecurityError" DOMException
をスローします。
search
セッターステップは次のとおりです。
this の 関連する Document が null の場合、何も行いません。
this の 関連する Document の origin が same origin-domain と一致しない場合、"SecurityError" DOMException
をスローします。
与えられた値が空文字列の場合、copyURL の query を null に設定します。
それ以外の場合、次のサブステップを実行します。
与えられた値から先頭の "?" を 1 つ削除したものを input とします。
copyURL の query を空文字列に設定します。
基本的な URL
解析 を input に対して実行し、null、関連する Document の ドキュメントの文字エンコーディング、copyURL を
url として、query state を state override として設定します。
Location-object navigate this を copyURL にナビゲートします。
hash
ゲッターステップは次のとおりです。
this の 関連する Document が null でなく、その origin が same origin-domain と一致しない場合、"SecurityError" DOMException
をスローします。
hash セッターステップは次のとおりです。
this の 関連する Document が null の場合、何も行いません。
this の 関連する Document の origin が same origin-domain と一致しない場合、"SecurityError" DOMException
をスローします。
与えられた値から先頭の "#" を 1 つ削除したものを input とします。
copyURL の fragment を空文字列に設定します。
基本的な URL 解析 を input に対して実行し、copyURL を url とし、fragment state を state override として設定します。
copyURL の fragment が this の url の fragment と一致する場合、何も行いません。
このベイルアウトは、スクロール時に冗長に
location.hash を設定する 配備済みコンテンツとの互換性のために必要です。他のフラグメントナビゲーションメカニズム、例えば location.href
セッターや location.assign()
には適用されません。
Location-object navigate this を copyURL にナビゲートします。
a 要素および area 要素の同等の API とは異なり、hash
セッターは空文字列を特別扱いしません。これは、配備済みスクリプトとの互換性を維持するためです。
assign(url)
メソッドステップは次のとおりです。
this の 関連する Document が null の場合、何も行いません。
this の 関連する Document の origin が same origin-domain と一致しない場合、"SecurityError" DOMException
をスローします。
urlRecord を URL のエンコーディングと解析 の結果として、url に基づき、エントリー設定オブジェクト に相対的に設定します。
urlRecord が失敗の場合、"SyntaxError" DOMException
をスローします。
Location-object navigate this を urlRecord にナビゲートします。
replace(url) メソッドステップは次のとおりです。
this の 関連する Document が null の場合、何も行いません。
urlRecord を URL のエンコーディングと解析 の結果として、url に基づき、エントリー設定オブジェクト に相対的に設定します。
urlRecord が失敗の場合、"SyntaxError" DOMException
をスローします。
Location-object navigate this を urlRecord にナビゲートし、"replace"
を指定します。
replace()
メソッドには意図的にセキュリティチェックがありません。
reload()
メソッドステップは次のとおりです。
document を this の 関連する Document として設定します。
document が null の場合、何も行いません。
document の origin が same origin-domain と一致しない場合、"SecurityError" DOMException
をスローします。
ancestorOrigins ゲッターステップは次のとおりです。
this の 関連する Document が null の場合、空の リスト を返します。
this の 関連する Document の origin が same origin-domain と一致しない場合、"SecurityError" DOMException
をスローします。
それ以外の場合、this の ancestor origins list を返します。
ancestorOrigins
属性の動作の詳細はまだ議論の余地があり、変更される可能性があります。詳細については issue #1918
を参照してください。
以前説明したように、Location
エキゾチックオブジェクトは、セキュリティ目的のために IDL 以上の追加ロジックを必要とします。Location
オブジェクトは、以下に明示的に指定されている場合を除き、通常の内部メソッドを使用する必要があります。
また、すべての Location オブジェクトには、作成時のプロパティを表す
[[DefaultProperties]] 内部スロットがあります。
IsPlatformObjectSameOrigin(this) が true の場合、! OrdinaryGetPrototypeOf(this) を返します。
null を返します。
! SetImmutablePrototype(this, V) を返します。
true を返します。
false を返します。
IsPlatformObjectSameOrigin(this) が true の場合:
desc を OrdinaryGetOwnProperty(this, P) として設定します。
this の [[DefaultProperties]] 内部スロットの値が P を含む場合、desc.[[Configurable]] を true に設定します。
desc を返します。
property を CrossOriginGetOwnPropertyHelper(this, P) として設定します。
property が undefined でない場合、property を返します。
CrossOriginPropertyFallback(P) を返します。
IsPlatformObjectSameOrigin(this) が true の場合:
this の [[DefaultProperties]] 内部スロットの値が P を含む場合、false を返します。
? OrdinaryDefineOwnProperty(this, P, Desc) を返します。
"SecurityError" DOMException
をスローします。
IsPlatformObjectSameOrigin(this) が true の場合、? OrdinaryGet(this, P, Receiver) を返します。
? CrossOriginGet(this, P, Receiver) を返します。
IsPlatformObjectSameOrigin(this) が true の場合、? OrdinarySet(this, P, V, Receiver) を返します。
? CrossOriginSet(this, P, V, Receiver) を返します。
IsPlatformObjectSameOrigin(this) が true の場合、? OrdinaryDelete(this, P) を返します。
"SecurityError" DOMException
をスローします。
IsPlatformObjectSameOrigin(this) が true の場合、OrdinaryOwnPropertyKeys(this) を返します。
CrossOriginOwnPropertyKeys(this) を返します。
History インターフェースすべての最新エンジンでサポートされています。
すべての最新エンジンでサポートされています。
enum ScrollRestoration { " auto " , " manual " };
[Exposed =Window ]
interface History {
readonly attribute unsigned long length ;
attribute ScrollRestoration scrollRestoration ;
readonly attribute any state ;
undefined go (optional long delta = 0);
undefined back ();
undefined forward ();
undefined pushState (any data , DOMString unused , optional USVString ? url = null );
undefined replaceState (any data , DOMString unused , optional USVString ? url = null );
};
history.length
すべての最新エンジンでサポートされています。
現在のセッション履歴エントリの総数を返します。 現在のナビゲーション対象のためのものです。
history.scrollRestoration
すべての最新エンジンでサポートされています。
現在のアクティブな セッション履歴エントリのスクロール復元モードを返します。
history.scrollRestoration = value
現在のアクティブな セッション履歴エントリのスクロール復元モードを valueに設定します。
history.state
すべての最新エンジンでサポートされています。
現在のアクティブな セッション履歴エントリのクラシックな履歴API状態を JavaScriptの値にデシリアライズして返します。
history.go()
現在のページを再読み込みします。
history.go(delta)
すべての最新エンジンでサポートされています。
現在のセッション履歴エントリの リストで指定された数だけ前後に移動します。
デルタがゼロの場合、現在のページを再読み込みします。
デルタが範囲外の場合、何も起こりません。
history.back()
すべての最新エンジンでサポートされています。
現在のセッション履歴エントリ リストで 1 つ前に戻ります。
前のページがない場合、何も起こりません。
history.forward()
すべての最新エンジンでサポートされています。
現在のセッション履歴エントリ リストで 1 つ前に進みます。
次のページがない場合、何も起こりません。
history.pushState(data, "")
すべての最新エンジンでサポートされています。
dataのシリアライズされた内容でクラシックな履歴API状態が設定された新しいエントリをセッション履歴に追加します。 新しいエントリの URL としてURLが使用されます。
(2 番目のパラメーターは歴史的な理由で存在しており、省略できません。空文字列を渡すことが伝統的です。)
history.pushState(data, "", url)
dataのシリアライズされた内容でクラシックな履歴API状態が設定され、urlに設定された新しいエントリをセッション履歴に追加します。
現在のドキュメントが
urlに書き換えられない場合、"SecurityError"
DOMExceptionがスローされます。
(2 番目のパラメーターは歴史的な理由で存在しており、省略できません。空文字列を渡すことが伝統的です。)
history.replaceState(data, "")
すべての最新エンジンでサポートされています。
現在のアクティブな セッション履歴エントリのクラシックな履歴API状態を dataの構造化クローンに更新します。
(2 番目のパラメーターは歴史的な理由で存在しており、省略できません。空文字列を渡すことが伝統的です。)
history.replaceState(data, "", url)
現在のアクティブな セッション履歴エントリのクラシックな履歴API状態を dataの構造化クローンに更新し、そのURLを urlに設定します。
現在のドキュメントが
urlに書き換えられない場合、"SecurityError"
DOMExceptionがスローされます。
(2 番目のパラメーターは歴史的な理由で存在しており、省略できません。空文字列を渡すことが伝統的です。)
Documentには、履歴オブジェクト、すなわちHistoryオブジェクトがあります。
historyのgetter手順は、thisの関連するDocumentの履歴オブジェクトを返すことです。
各Historyオブジェクトには、最初はnullである状態があります。
各Historyオブジェクトには、非負の整数で初期値が0の長さがあります。
各Historyオブジェクトには、非負の整数で初期値が0のインデックスがあります。
インデックスは直接公開されませんが、同期ナビゲーション中に長さの変化から推測することができます。実際、それがその用途です。
lengthのgetter手順は以下の通りです:
thisの関連するグローバルオブジェクトの関連するDocumentが完全にアクティブでない場合、"セキュリティエラー"のDOMExceptionを投げます。
scrollRestorationのgetter手順は以下の通りです:
thisの関連するグローバルオブジェクトの関連するDocumentが完全にアクティブでない場合、"セキュリティエラー"のDOMExceptionを投げます。
scrollRestorationのsetter手順は以下の通りです:
thisの関連するグローバルオブジェクトの関連するDocumentが完全にアクティブでない場合、"セキュリティエラー"のDOMExceptionを投げます。
thisのナビゲーブルノードのアクティブなセッション履歴エントリのスクロール復元モードを指定された値に設定します。
stateのgetter手順は以下の通りです:
thisの関連するグローバルオブジェクトの関連するDocumentが完全にアクティブでない場合、"セキュリティエラー"のDOMExceptionを投げます。
go(delta)のメソッド手順は、delta traverseを実行し、deltaを指定してthisを渡します。
back()のメソッド手順は、delta traverseを実行し、-1を指定してthisを渡します。
forward()のメソッド手順は、delta traverseを実行し、+1を指定してthisを渡します。
delta traverseをdeltaを指定してHistoryオブジェクトhistoryに対して行うための手順は以下の通りです:
documentをhistoryの関連するグローバルオブジェクトの関連するDocumentとします。
documentが完全にアクティブでない場合、"セキュリティエラー"のDOMExceptionを投げます。
deltaが0の場合、documentのナビゲーブルノードをリロードし、終了します。
履歴をdeltaでトラバースし、documentのナビゲーブルノードのトラバーサブルナビゲーブルをdeltaを指定して実行し、ソースドキュメントをdocumentに設定します。
pushState(data, unused, url)のメソッド手順は、共有履歴のpush/replace state手順を実行し、this、data、url、および"push"を指定します。
replaceState(data, unused, url)のメソッド手順は、共有履歴のpush/replace state手順を実行し、this、data、url、および"replace"を指定します。
共有履歴のpush/replace state手順は、History、dataの値、スカラー値文字列またはnull、url、および履歴処理の動作であるhistoryHandlingを指定して次の手順を実行します:
documentをhistoryの関連Documentとします。
documentが完全にアクティブでない場合、"セキュリティエラー"のDOMExceptionを投げます。
任意で、終了します。(例えば、ユーザーエージェントが、タイマーで呼び出された場合、または明確なユーザー操作に応じてトリガーされないイベントリスナーから呼び出された場合、または迅速に連続して呼び出された場合にこれらのメソッドを許可しないかもしれません。)
serializedDataをStructuredSerializeForStorage(data)の結果とします。例外が発生した場合は再スローします。
newURLをdocumentのURLとします。
もしurlがnullでないか空の文字列でない場合、次の手順を実行します:
newURLを、urlと、historyの関連する設定オブジェクトを基にしたURLのエンコード解析の結果に設定します。
もしnewURLが失敗した場合、"セキュリティエラー"のDOMExceptionを投げます。
もしdocumentがnewURLに対してURLを書き換えることができない場合、"セキュリティエラー"のDOMExceptionを投げます。
ここでの空の文字列に対する特別な扱いは歴史的なものであり、location.href = ""(これは空の文字列に対してURL解析を行います)とhistory.pushState(null, "", "")(これはそれをバイパスします)を比較した場合、異なる結果のURLが生成されることになります。
navigationをhistoryの関連するグローバルオブジェクトのナビゲーションAPIとします。
continueをpush/replace/reload
navigateイベントを発火した結果として取得し、navigationに対して実行し、historyHandlingをnavigationTypeとして設定し、isSameDocumentをtrueとして設定し、destinationURLをnewURLとして設定し、classicHistoryAPIStateをserializedDataとして設定します。
もしcontinueがfalseである場合、終了します。
documentとnewURLを指定してURLと履歴の更新手順を実行し、serializedDataを設定し、historyHandlingを設定します。
ユーザーエージェントは、ページごとにセッション履歴に追加される状態オブジェクトの数を制限することができます。ページが実装定義の制限に達した場合、ユーザーエージェントは、新しいエントリを追加した後、セッション履歴内のそのDocumentオブジェクトに対する最初のエントリの直後にエントリを削除する必要があります。(したがって、状態履歴は削除に対してFIFOバッファとして動作し、ナビゲーションに対してLIFOバッファとして動作します。)
Documentがdocumentであり、次のアルゴリズムがtrueを返す場合、URLを書き換えることができます。
documentURLをdocumentのURLとします。
もしtargetURLとdocumentURLが、そのスキーム、ユーザー名、パスワード、ホスト、またはポートが異なる場合、falseを返します。
もしtargetURLのスキームがHTTP(S)スキームである場合、trueを返します。
もしtargetURLのスキームが"file"である場合:
もしtargetURLとdocumentURLが、そのパスコンポーネントが異なる場合、falseを返します。
trueを返します。
もしtargetURLとdocumentURLが、そのパスコンポーネントまたはクエリコンポーネントが異なる場合、falseを返します。
他の種類のURLでは、フラグメントの違いのみが許容されます。
trueを返します。
| documentのURL | targetURL | URLを書き換えることができるか |
|---|---|---|
https://example.com/home |
https://example.com/home#about |
✅ |
https://example.com/home |
https://example.com/home?page=shop |
✅ |
https://example.com/home |
https://example.com/shop |
✅ |
https://example.com/home |
https://user:pass@example.com/home |
❌ |
https://example.com/home |
http://example.com/home |
❌ |
file:///path/to/x |
file:///path/to/x#hash |
✅ |
file:///path/to/x |
file:///path/to/x?search |
✅ |
file:///path/to/x |
file:///path/to/y |
❌ |
about:blank |
about:blank#hash |
✅ |
about:blank |
about:blank?search |
❌ |
about:blank |
about:srcdoc |
❌ |
data:text/html,foo |
data:text/html,foo#hash |
✅ |
data:text/html,foo |
data:text/html,foo?search |
❌ |
data:text/html,foo |
data:text/html,bar |
❌ |
data:text/html,foo |
data:bar |
❌ |
blob:https://example.com/77becafe-657b-4fdc-8bd3-e83aaa5e8f43 |
blob:https://example.com/77becafe-657b-4fdc-8bd3-e83aaa5e8f43#hash |
✅ |
blob:https://example.com/77becafe-657b-4fdc-8bd3-e83aaa5e8f43 |
blob:https://example.com/77becafe-657b-4fdc-8bd3-e83aaa5e8f43?search |
❌ |
blob:https://example.com/77becafe-657b-4fdc-8bd3-e83aaa5e8f43 |
blob:https://example.com/anything |
❌ |
blob:https://example.com/77becafe-657b-4fdc-8bd3-e83aaa5e8f43 |
blob:path |
❌ |
DocumentのURLのみが重要であり、そのオリジンは関係ありません。たとえば、継承されたオリジンを持つabout:blankドキュメントや、サンドボックス化されたiframe、またはdocument.domainセッターが使用された場合などでオリジンが一致しないことがあります。
ユーザーが座標に沿って移動できるゲームを考えてみましょう。ユーザーは常にどこかの座標にいて、その座標に対応するページをブックマークして後で戻ることができます。
そのようなゲームでx=5の位置を実装する静的ページは、次のようになります:
<!DOCTYPE HTML>
<!-- このページは https://example.com/line?x=5 です -->
< html lang = "ja" >
< title > ラインゲーム - 5</ title >
< p > あなたはラインの座標5にいます。</ p >
< p >
< a href = "?x=6" > 6に進む</ a > か、< a href = "?x=4" > 4に戻る</ a > ?
</ p >
このようなシステムの問題は、ユーザーがクリックするたびに、ページ全体がリロードされることです。代わりに、スクリプトを使用してこれを解決する方法を以下に示します:
<!DOCTYPE HTML>
<!-- このページは https://example.com/line?x=5 です -->
< html lang = "ja" >
< title > ラインゲーム - 5</ title >
< p > あなたはラインの座標 < span id = "coord" > 5</ span > にいます。</ p >
< p >
< a href = "?x=6" onclick = "go(1); return false;" > 6に進む</ a > か、< a href = "?x=4" onclick = "go(-1); return false;" > 4に戻る</ a > ?
</ p >
< script >
var currentPage = 5 ; // サーバーによって事前入力されています
function go( d) {
setupPage( currentPage + d);
history. pushState( currentPage, "" , '?x=' + currentPage);
}
onpopstate = function ( event) {
setupPage( event. state);
}
function setupPage( page) {
currentPage = page;
document. title = 'ラインゲーム - ' + currentPage;
document. getElementById( 'coord' ). textContent = currentPage;
document. links[ 0 ]. href = '?x=' + ( currentPage+ 1 );
document. links[ 0 ]. textContent = '6に進む' + ( currentPage+ 1 );
document. links[ 1 ]. href = '?x=' + ( currentPage- 1 );
document. links[ 1 ]. textContent = '4に戻る' + ( currentPage- 1 );
}
</ script >
スクリプトのないシステムでは、これも前の例と同じように機能します。しかし、スクリプトをサポートしているユーザーは、同じ体験をするためにネットワークアクセスが不要になるため、はるかに高速に移動できます。さらに、単にナイーブなスクリプトベースのアプローチを使用した場合とは対照的に、ブックマークやセッション履歴のナビゲーションが引き続き機能します。
上記の例では、pushState()メソッドのdata引数は、ユーザーが移動するたびにスクリプトがURLを解析しなくても済むように、サーバーに送信される情報と同じですが、より便利な形式になっています。
ほとんどのアプリケーションは、すべての履歴エントリに同じスクロール復元モード値を使用したいと考えています。これを実現するために、scrollRestoration属性をできるだけ早く(たとえば、最初のscript要素の中で)設定し、履歴セッションに追加されるエントリが、希望するスクロール復元モードを確実に取得するようにします。
< head >
< script >
if ( 'scrollRestoration' in history)
history. scrollRestoration = 'manual' ;
</ script >
</ head >
このセクションは規範的ではありません。
ナビゲーションAPIは、グローバルnavigationプロパティによって提供され、ナビゲーションと履歴エントリを管理するためのモダンでウェブアプリケーションに焦点を当てた方法を提供します。これは、従来のlocationおよびhistoryAPIの後継です。
このAPIが提供する機能の1つは、セッション履歴エントリを検査することです。例えば、次のコードはエントリのURLを順序付きリストに表示します:
const ol = document. createElement( "ol" );
ol. start = 0 ; // 項目番号がエントリインデックスと一致するように
for ( const entry of navigation. entries()) {
const li = document. createElement( "li" );
if ( entry. index < navigation. currentEntry. index) {
li. className = "backward" ;
} else if ( entry. index > navigation. currentEntry. index) {
li. className = "forward" ;
} else {
li. className = "current" ;
}
li. textContent = entry. url;
ol. append( li);
}
navigation.entries()配列には、NavigationHistoryEntryインスタンスが含まれており、ここで示されているurlおよびindexプロパティに加えて他の有用なプロパティを持っています。配列には、現在のナビゲーブルを表すNavigationHistoryEntryオブジェクトのみが含まれているため、その内容はiframeなどのナビゲーブルコンテナ内でのナビゲーションや、iframe内でナビゲーションAPI自体が使用されている場合の親ナビゲーブルのナビゲーションによって影響を受けません。また、同一オリジンのセッション履歴エントリを表すNavigationHistoryEntryオブジェクトのみを含むため、ユーザーが現在のオリジンの前後に他のオリジンを訪問していた場合、それに対応するNavigationHistoryEntryは含まれません。
ナビゲーションAPIは、ナビゲート、リロード、または履歴の移動にも使用できます:
< button onclick = "navigation.reload()" > Reload</ button >
< input type = "url" id = "navigationURL" >
< button onclick = "navigation.navigate(navigationURL.value)" > Navigate</ button >
< button id = "backButton" onclick = "navigation.back()" > Back</ button >
< button id = "forwardButton" onclick = "navigation.forward()" > Forward</ button >
< select id = "traversalDestinations" ></ select >
< button id = "goButton" onclick = "navigation.traverseTo(traversalDestinations.value)" > Traverse To</ button >
< script >
backButton. disabled = ! navigation. canGoBack;
forwardButton. disabled = ! navigation. canGoForward;
for ( const entry of navigation. entries()) {
traversalDestinations. append( new Option( entry. url, entry. key));
}
</ script >
トラバースは再び同一オリジンの目的地に制限されることに注意してください。つまり、例えば前のセッション履歴エントリが別のオリジンのページである場合、navigation.canGoBackはfalseになります。
ナビゲーションAPIの最も強力な部分は、現在のナビゲーブルでほとんどのナビゲーションやトラバースが発生するたびに発火するnavigateイベントです。
navigation. onnavigate = event => {
console. log( event. navigationType); // "push", "replace", "reload", "traverse" のいずれか
console. log( event. destination. url);
console. log( event. userInitiated);
// その他の 便利なプロパティも参照
};
(このイベントは、ロケーションバーでのナビゲーションの開始や、他のウィンドウから開始されたナビゲーションで、ナビゲーションの目的地が新しいドキュメントである場合には発火しません。)
多くの場合、このイベントのcancelableプロパティはtrueになります。つまり、このイベントはpreventDefault()を使用してキャンセルできます。
navigation. onnavigate = event => {
if ( event. cancelable && isDisallowedURL( event. destination. url)) {
alert( `Please don't go to ${ event. destination. url} !` );
event. preventDefault();
}
あるトラバースナビゲーション、例えば子ナビゲーブル内でのナビゲーションや、他のオリジンへの移行、またはユーザーが前回のpreventDefault()の呼び出し直後に再度トラバースしようとする場合には、cancelableプロパティはfalseになります。
NavigateEventのintercept()メソッドは、ナビゲーションを同一ドキュメントナビゲーションに変換するためにインターセプトすることを可能にします。
navigation. addEventListener( "navigate" , e => {
// いくつかのナビゲーション、例えばオリジンを跨ぐナビゲーションなどはインターセプトできません。
// それらは通常どおりブラウザに処理させます。
if ( ! e. canIntercept) {
return ;
}
// 同様に、フラグメントナビゲーションやダウンロードリクエストもインターセプトしません。
if ( e. hashChange || e. downloadRequest !== null ) {
return ;
}
const url = new URL( event. destination. url);
if ( url. pathname. startsWith( "/articles/" )) {
e. intercept({
async handler() {
// URLはすでに変更されているため、新しいコンテンツをフェッチしている間にプレースホルダーを表示します。例えばスピナーやロード画面など。
renderArticlePagePlaceholder();
// 新しいコンテンツをフェッチし、準備が整い次第表示します。
const articleContent = await getArticleContent( url. pathname, { signal: e. signal });
renderArticlePage( articleContent);
}
});
}
});
handler関数は、ナビゲーションの非同期処理の進行状況と成功または失敗を表すためにPromiseを返すことができます。Promiseがまだ保留中の場合、ブラウザUIはナビゲーションが進行中として扱うことができます(例えば、ローディングスピナーを表示するなど)。ナビゲーションAPIの他の部分もこれらのPromiseに敏感であり、例えばnavigation.navigate()の戻り値にも影響を与えます。
const { committed, finished } = await navigation. navigate( "/articles/the-navigation-api-is-cool" );
// committedプロミスは、URLが変更された後に解決します。これは、NavigateEventがキャンセルされていない限り、即座に発生します。
await committed;
// finishedプロミスは、handler()によって返されたPromiseが解決されると解決します。これは、記事がダウンロードされてレンダリングされると完了します。(または、handler()が途中で失敗した場合は拒否されます)。
await finished;
Navigationインターフェース[Exposed =Window ]
interface Navigation : EventTarget {
sequence <NavigationHistoryEntry > entries ();
readonly attribute NavigationHistoryEntry ? currentEntry ;
undefined updateCurrentEntry (NavigationUpdateCurrentEntryOptions options );
readonly attribute NavigationTransition ? transition ;
readonly attribute NavigationActivation ? activation ;
readonly attribute boolean canGoBack ;
readonly attribute boolean canGoForward ;
NavigationResult navigate (USVString url , optional NavigationNavigateOptions options = {});
NavigationResult reload (optional NavigationReloadOptions options = {});
NavigationResult traverseTo (DOMString key , optional NavigationOptions options = {});
NavigationResult back (optional NavigationOptions options = {});
NavigationResult forward (optional NavigationOptions options = {});
attribute EventHandler onnavigate ;
attribute EventHandler onnavigatesuccess ;
attribute EventHandler onnavigateerror ;
attribute EventHandler oncurrententrychange ;
};
dictionary NavigationUpdateCurrentEntryOptions {
required any state ;
};
dictionary NavigationOptions {
any info ;
};
dictionary NavigationNavigateOptions : NavigationOptions {
any state ;
NavigationHistoryBehavior history = "auto";
};
dictionary NavigationReloadOptions : NavigationOptions {
any state ;
};
dictionary NavigationResult {
Promise <NavigationHistoryEntry > committed ;
Promise <NavigationHistoryEntry > finished ;
};
enum NavigationHistoryBehavior {
" auto " ,
" push " ,
" replace "
};
各Windowには、ナビゲーションAPIが関連付けられており、これはNavigationオブジェクトです。Windowオブジェクトが作成されると、そのナビゲーションAPIは、そのWindowオブジェクトの関連レルムで作成された新しいNavigationオブジェクトに設定される必要があります。
navigationゲッターの手順は、thisのナビゲーションAPIを返すことです。
以下は、イベントハンドラー(およびそれに対応するイベントハンドラーイベントタイプ)であり、イベントハンドラーIDL属性として、Navigationインターフェースを実装するすべてのオブジェクトによってサポートされる必要があります。
| イベントハンドラー | イベントハンドラーイベントタイプ |
|---|---|
onnavigate |
navigate |
onnavigatesuccess |
navigatesuccess
|
onnavigateerror |
navigateerror
|
oncurrententrychange |
currententrychange
|
各Navigationには、関連する
エントリリスト、リストがあり、それは最初は空のNavigationHistoryEntry
オブジェクトのリストです。
各Navigationには、関連する現在のエントリインデックスがあり、それは最初は-1の整数です。
Navigation
navigationの現在のエントリは、次のステップを実行した結果です:
navigationがエントリとイベントが無効になっている場合、 nullを返します。
アサート: navigationの現在のエントリインデックスは-1ではありません。
navigationのエントリリスト[navigationの現在のエントリインデックス]を返します。
Navigation
navigationがエントリとイベントが無効である場合、それは次のステップがtrueを返す場合です:
documentをnavigationの関連するグローバルオブジェクトの関連するDocumentに設定します。
documentが完全にアクティブでない場合、trueを返します。
documentの初期about:blankがtrueの場合、trueを返します。
falseを返します。
セッション履歴エントリ sheのNavigation
navigationのナビゲーションAPIエントリインデックスを取得するには、次のステップを実行します:
indexを0に設定します。
各 nheのnavigationのエントリリストを次のステップで繰り返します:
nheのセッション履歴エントリがsheと等しい場合、indexを返します。
indexを1増やします。
-1を返します。
ナビゲーションAPI全体で使用される主要な型の1つは、NavigationType列挙型です:
enum NavigationType {
" push " ,
" replace " ,
" reload " ,
" traverse "
};
これは主にウェブ開発者に見える「ナビゲーション」のタイプを捉えたもので、(他の場所で説明されているように)この標準の単一のナビゲートアルゴリズムとは正確には一致しません。各値の意味は次のとおりです:
push"
push」として終了するか、history.pushState()への呼び出しに対応します。
replace"
replace」として終了するか、history.replaceState()への呼び出しに対応します。
reload"
traverse"
NavigationType列挙型の値の空間は、仕様内部の履歴処理の挙動型の値の空間のスーパーセットです。この標準のいくつかの部分は、この重複を利用して、NavigationTypeを期待するアルゴリズムに履歴処理の挙動を渡すことがあります。
新しいドキュメントのためにナビゲーションAPIエントリを初期化するには、
Navigation
navigation、リストとしてのセッション履歴エントリ newSHEs、
およびセッション履歴エントリ
initialSHEを指定します。
アサート: navigationの現在のエントリインデックスが -1であることを確認します。
もしnavigationがエントリとイベントが無効である場合、 そのまま終了します。
各 newSHEについてnewSHEsを次のように処理します:
newNHEをnavigationの新しい NavigationHistoryEntryとして作成します。
newNHEのセッション履歴エントリを newSHEに設定します。
newSHEsはもともとナビゲーションAPIのためのセッション履歴エントリを取得から来たものであり、各newSHEはinitialSHEと同じオリジンで連続しています。
navigationの現在のエントリインデックスを、 initialSHEのnavigation内でのナビゲーションAPIエントリインデックスの取得結果に設定します。
再アクティベーションのためにナビゲーションAPIエントリを更新するには、
Navigation
navigation、リストとしてのセッション履歴エントリ newSHEs、
およびセッション履歴エントリ
reactivatedSHEを指定します。
もしnavigationがエントリとイベントが無効である場合、 そのまま終了します。
newNHEsを新しい空のリストとして設定します。
各 newSHEについてnewSHEsを次のように処理します:
newNHEをnullに設定します。
もしoldNHEsが含む場合、
セッション履歴エントリが
newSHEであるNavigationHistoryEntry
matchingOldNHEを次のように処理します:
newNHEをmatchingOldNHEに設定します。
Remove matchingOldNHEをoldNHEsから削除します。
それ以外の場合:
newNHEをnavigationの新しいNavigationHistoryEntryとして作成します。
newNHEのセッション履歴エントリをnewSHEに設定します。
Append newNHEをnewNHEsに追加します。
newSHEsはもともとナビゲーションAPIのためのセッション履歴エントリを取得から来たものであり、各newSHEはreactivatedSHEと同じオリジンで連続しています。
このループの終わりまでに、oldNHEsに残っているすべてのNavigationHistoryEntryは、
セッション履歴エントリであり、Documentがbfcache内にあったときに破棄されたものを表しています。
navigationのエントリリストをnewNHEsに設定します。
navigationの現在のエントリインデックスを、reactivatedSHEのnavigation内でのナビゲーションAPIエントリインデックスの取得結果に設定します。
グローバルタスクをキューに追加し、 navigationの関連するグローバルオブジェクトで次のステップを実行します:
各 disposedNHEについてoldNHEsを次のように処理します:
「dispose」イベントを発火し、disposedNHEに送信します。
これらのステップをタスクで遅延させるのは、dispose
イベントがpageshow
イベントの後に発火されることを保証するためです。これにより、pageshow
が再アクティベーション後にページが受け取る最初のイベントになります。
(ただし、このアルゴリズムの残りは、pageshow
イベントが発火する前に実行されます。これにより、navigation.entries()
およびnavigation.currentEntry
の値が正しく更新され、pageshow
イベントハンドラ内で使用できるようになります。)
同一ドキュメントナビゲーションのためにナビゲーションAPIエントリを更新するには、
Navigation
navigation、セッション履歴エントリ
destinationSHE、
およびNavigationType
navigationTypeを指定します:
もしnavigationがエントリとイベントが無効である場合、 そのまま終了します。
oldCurrentNHEをnavigationの現在のエントリとして設定します。
disposedNHEsを新しい空のリストとして設定します。
もしnavigationTypeが「traverse」である場合:
navigationの現在のエントリインデックスを、 destinationSHEのnavigation内でのナビゲーションAPIエントリインデックスの取得結果に設定します。
アサート: navigationの現在のエントリインデックスが -1ではないことを確認します。
このアルゴリズムは同一ドキュメントのトラバーサルにのみ呼び出されます。クロスドキュメントのトラバーサルは、代わりに新しいドキュメントのためにナビゲーションAPIエントリを初期化するか、 再アクティベーションのためにナビゲーションAPIエントリを更新します。
それ以外の場合、もしnavigationTypeが「push」である場合:
navigationの現在のエントリインデックスをnavigationの現在のエントリインデックス + 1に設定します。
iをnavigationの現在のエントリインデックスに設定します。
それ以外の場合、もしnavigationTypeが「replace」である場合:
Append oldCurrentNHEをdisposedNHEsに追加します。
もしnavigationTypeが「push」
または
「replace」
である場合:
newNHEをnavigationの新しいNavigationHistoryEntryとして作成します。
newNHEのセッション履歴エントリをdestinationSHEに設定します。
navigationのエントリリスト[navigationの現在のエントリインデックス]をnewNHEに設定します。
もしnavigationの進行中のAPIメソッドトラッカーがnullでない場合、 コミットされたエントリについて通知し、 navigationの進行中のAPIメソッドトラッカーとnavigationの現在のエントリを指定します。
これは、disposeまたはcurrententrychangeイベントを発火する前に行うことが重要です。イベントハンドラが別のナビゲーションを開始したり、navigationの進行中のAPIメソッドトラッカーの値を変更する可能性があるためです。
スクリプトの実行準備を行う、 navigationの関連する設定オブジェクトを指定します。
なぜこれを行うかについては、他のナビゲーションAPIイベントに関する議論を参照してください。
「currententrychange」イベントを発火し、
navigationでNavigationCurrentEntryChangeEvent
を使用し、そのnavigationType
属性をnavigationTypeに初期化し、from属性をoldCurrentNHEに初期化します。
各 disposedNHEについてdisposedNHEsを次のように処理します:
「dispose」イベントを発火し、 disposedNHEに送信します。
スクリプト実行後のクリーンアップを行い、 navigationの関連する設定オブジェクトを指定します。
実装において、同一ドキュメントのナビゲーションは、セッション履歴エントリがセッション履歴エントリリストの後ろから消えて破棄される原因となることがあります。これは上記のアルゴリズム(またはこの標準の他の部分)ではまだ対処されていません。このような場合の正しい動作を定義する進捗状況については、issue #8620を参照してください。
NavigationHistoryEntry
インターフェース[Exposed =Window ]
interface NavigationHistoryEntry : EventTarget {
readonly attribute USVString ? url ;
readonly attribute DOMString key ;
readonly attribute DOMString id ;
readonly attribute long long index ;
readonly attribute boolean sameDocument ;
any getState ();
attribute EventHandler ondispose ;
};
entry.url
このナビゲーション履歴エントリのURL。
このエントリが現在のDocument
と異なるsameDocument
(falseの場合)に対応している場合、この値はnullを返すことがあります。また、そのDocument
が「no-referrer」または「origin」のリファラーポリシーで取得された場合、該当するDocument
は、同一オリジンの他のページからでもURLを隠していることを示しています。
entry.key
このナビゲーション履歴エントリのナビゲーション履歴リスト内での位置を表す、ユーザーエージェント生成のランダムなUUID文字列。この値は、「replace」
ナビゲーションのためにこのエントリを置き換える他のNavigationHistoryEntryインスタンスによって再利用され、リロードやセッションの復元でも維持されます。
これは、navigation.traverseTo(key)
を使用して、ナビゲーション履歴リスト内のこのエントリに戻るために役立ちます。
entry.id
この特定のナビゲーション履歴エントリを表す、ユーザーエージェント生成のランダムなUUID文字列。この値は、他のNavigationHistoryEntry
インスタンスによって再利用されることはありません。この値はリロードやセッションの復元でも維持されます。
これは、他のストレージAPIを使用して、このナビゲーション履歴エントリにデータを関連付けるのに役立ちます。
entry.index
このNavigationHistoryEntry
がnavigation.entries()
内のどの位置にあるかを示します。ナビゲーション履歴エントリリストにない場合は−1を返します。
entry.sameDocument
このナビゲーション履歴エントリが現在のDocument
と同じかどうかを示します。このエントリがフラグメントナビゲーションやシングルページアプリのナビゲーションを表す場合、これはtrueになります。
entry.getState()
このエントリに保存された状態のデシリアライズを返します。これはnavigation.navigate()
またはnavigation.updateCurrentEntry()
を使用してエントリに追加されたものです。この状態はリロードやセッションの復元でも維持されます。
一般的に、状態値がプリミティブでない限り、entry.getState() !== entry.getState()であることに注意してください。なぜなら、毎回新しいデシリアライズが返されるためです。
この状態は、従来の履歴APIのhistory.state
とは無関係です。
各NavigationHistoryEntry
には、関連するセッション履歴エントリがあり、これはセッション履歴エントリです。
NavigationHistoryEntry
nheのキーは、次のアルゴリズムの戻り値によって決まります:
nheの関連するグローバルオブジェクトの関連するDocument
が完全にアクティブでない場合、空の文字列を返します。
nheのセッション履歴エントリのナビゲーションAPIキー を返します。
NavigationHistoryEntry
nheのIDは、次のアルゴリズムの戻り値によって決まります:
nheの関連するグローバルオブジェクトの関連するDocument
が完全にアクティブでない場合、空の文字列を返します。
nheのセッション履歴エントリのナビゲーションAPI ID を返します。
NavigationHistoryEntry
nheのインデックスは、次のアルゴリズムの戻り値によって決まります:
nheの関連するグローバルオブジェクトの関連するDocument
が完全にアクティブでない場合、−1を返します。
ナビゲーションAPIエントリインデックスの取得の結果を返します。 これは、thisのセッション履歴エントリ のnavigation内での結果です。
urlのゲッターステップは次のとおりです:
documentをthisの関連するグローバルオブジェクト
の関連するDocumentに設定します。
documentが完全にアクティブでない場合、空の文字列を返します。
sheをthisのセッション履歴エントリに設定します。
もしsheのドキュメントがdocumentと等しくない場合、またsheのドキュメント状態のリファラーポリシー
が「no-referrer」または「origin」である場合、nullを返します。
indexのゲッターステップは、thisのインデックスを返すことです。
sameDocumentのゲッターステップは次のとおりです:
documentをthisの関連するグローバルオブジェクト
の関連するDocumentに設定します。
documentが完全にアクティブでない場合、falseを返します。
thisのセッション履歴エントリのドキュメントがdocumentと等しい場合はtrueを返し、それ以外の場合はfalseを返します。
getState()メソッドステップは次のとおりです:
thisの関連するグローバルオブジェクトの関連するDocument
が完全にアクティブでない場合、undefinedを返します。
StructuredDeserialize(thisのセッション履歴エントリのナビゲーションAPIステート)を返します。 例外が発生した場合は再スローします。
これは理論的には、十分なメモリが利用できない場合に大きなArrayBufferをデシリアライズしようとした場合に、例外をスローする可能性があります。
次に示すのは、すべてのNavigationHistoryEntry
インターフェースを実装するオブジェクトが、イベントハンドラーIDL属性としてサポートしなければならないイベントハンドラーとその対応するイベントハンドラーイベントタイプです:
| イベントハンドラー | イベントハンドラーイベントタイプ |
|---|---|
ondispose
| dispose
|
entries = navigation.entries()
NavigationHistoryEntry
インスタンスの配列を返します。これらは現在のナビゲーション履歴エントリリスト、すなわち、このナビゲーブルのためのすべてのセッション履歴エントリを表し、
それらは同一オリジンであり、現在のセッション履歴エントリに連続しています。
navigation.currentEntry
現在のセッション履歴エントリに対応するNavigationHistoryEntry
を返します。
navigation.updateCurrentEntry({ state })
現在のセッション履歴エントリのナビゲーションAPIステート
を更新しますが、navigation.reload()
のようにナビゲーションは行いません。
このメソッドは、すでに行われたページの更新をナビゲーションAPIステートに反映させるために使用するのが最適です。ステートの更新がページの更新を駆動することを意図している場合は、代わりにnavigation.navigate()
またはnavigation.reload()を使用します。これによりnavigate
イベントがトリガーされます。
navigation.canGoBack
現在の現在のセッション履歴エントリ(すなわち、currentEntry)
がナビゲーション履歴エントリリスト(すなわち、entries())
の最初のものではない場合、trueを返します。これは、このナビゲーブルの以前のセッション履歴エントリ
が存在し、そのドキュメント状態のオリジン
が現在のDocumentのオリジン
と同一オリジンであることを意味します。
navigation.canGoForward
現在の現在のセッション履歴エントリ(すなわち、currentEntry)
がナビゲーション履歴エントリリスト(すなわち、entries())
の最後のものではない場合、trueを返します。これは、このナビゲーブルの次のセッション履歴エントリ
が存在し、そのドキュメント状態のオリジン
が現在のDocumentのオリジン
と同一オリジンであることを意味します。
entries()
メソッドの手順は次のとおりです:
もしthisがエントリとイベントが無効である場合、空のリストを返します。
Web
IDLのシーケンスタイプ変換ルールにより、これにより各呼び出しで新しいJavaScript配列オブジェクトが作成されることを思い出してください。つまり、navigation.entries() !== navigation.entries()となります。
currentEntryのゲッターステップは、現在のエントリをthisから返すことです。
updateCurrentEntry(options)
メソッドの手順は次のとおりです:
もしcurrentがnullである場合、"InvalidStateError" DOMExceptionをスローします。
serializedStateを、StructuredSerializeForStorage(options["state"])として取得し、例外を再スローします。
currentのセッション履歴エントリのナビゲーションAPIステートをserializedStateに設定します。
イベントを発火し、thisでNavigationCurrentEntryChangeEventを使用し、そのnavigationType属性をnullに初期化し、そのfrom属性をcurrentに初期化します。
canGoBackのゲッターステップは次のとおりです:
もしthisがエントリとイベントが無効である場合、falseを返します。
アサート: thisの現在のエントリインデックスが-1でないことを確認します。
もしthisの現在のエントリインデックスが0である場合、falseを返します。
trueを返します。
canGoForwardのゲッターステップは次のとおりです:
もしthisがエントリとイベントが無効である場合、falseを返します。
アサート: thisの現在のエントリインデックスが-1でないことを確認します。
もしthisの現在のエントリインデックスがthisのエントリリストのサイズ-1と等しい場合、falseを返します。
trueを返します。
{ committed, finished } = navigation.navigate(url)
{ committed, finished } = navigation.navigate(url, options)
現在のページを指定されたurlにナビゲートします。optionsには次の値を含めることができます:
historyを"replace"に設定すると、現在のセッション履歴エントリを置き換え、新しいものを追加せずに済みます。
stateを任意のシリアライズ可能な値に設定できます。これにより、ナビゲーションが完了した後、同一ドキュメントのナビゲーションの場合にnavigation.currentEntry.getState()で取得される状態が設定されます。(クロスドキュメントナビゲーションの場合は無視されます。)
デフォルトでは、これにより完全なナビゲーション(つまり、現在のURLとフラグメントだけが異なる場合を除き、クロスドキュメントナビゲーション)が実行されます。navigateEvent.intercept()メソッドを使用して、これを同一ドキュメントナビゲーションに変換することができます。
返されるプロミスの挙動は次のとおりです:
ナビゲーションが中断された場合、両方のプロミスは"AbortError"DOMExceptionで拒否されます。
navigateEvent.intercept()メソッドを使用して作成された同一ドキュメントのナビゲーションの場合、committedは即座に解決され、finishedは、intercept()に渡されたハンドラーによって返されるプロミスに従って解決または拒否されます。
他の同一ドキュメントのナビゲーション(例: 非インターセプトされたフラグメントナビゲーション)の場合、両方のプロミスは即座に解決されます。
クロスドキュメントのナビゲーションや、204または205ステータス、またはサーバーから`Content-Disposition: attachment`ヘッダーフィールドが返されるナビゲーションの場合、両方のプロミスは決して解決されません。
いずれの場合も、返されたプロミスが解決されると、それはナビゲート先のNavigationHistoryEntryになります。
{ committed, finished } = navigation.reload(options)
現在のページをリロードします。optionsには、infoとstateを含めることができ、これらは上記の説明に従います。
デフォルトの動作である、ネットワークまたはキャッシュからの現在のページのリロードは、navigateEvent.intercept()メソッドを使用してオーバーライドできます。これを行うと、この呼び出しは状態の更新または適切なinfoの伝達のみを行い、navigateイベントハンドラーが実行するアクションを引き継ぎます。
返されたプロミスの挙動は次のとおりです:
リロードがnavigateEvent.intercept()メソッドを使用してインターセプトされた場合、committedは即座に解決され、finishedは、intercept()に渡されたハンドラーによって返されるプロミスに従って解決または拒否されます。
それ以外の場合、両方のプロミスは決して解決されません。
{ committed, finished } = navigation.traverseTo(key)
{ committed, finished } = navigation.traverseTo(key, { info })
最も近い セッション履歴エントリ に NavigationHistoryEntry
の指定された key に一致するエントリまで遡る。info
は任意の値に設定することができ、それは対応する info
プロパティに入力される。対応する NavigateEvent
のプロパティに入力される。
そのセッション履歴エントリへの遷移が既に進行中である場合、このメソッドはその元の遷移のプロミスを返し、infoは無視されます。
返されたプロミスの挙動は次のとおりです:
指定されたkeyに一致するNavigationHistoryEntryがnavigation.entries()に存在しない場合、両方のプロミスは"InvalidStateError"DOMExceptionで拒否されます。
navigateEvent.intercept()メソッドでインターセプトされた同一ドキュメントの遷移の場合、committedは遷移が処理され、navigation.currentEntryが更新され次第、満たされ、finishedは、intercept()に渡されたハンドラーによって返されるプロミスに従って満たされるか、または拒否されます。
非インターセプトされた同一ドキュメントの遷移の場合、両方のプロミスは遷移が処理されnavigation.currentEntryが更新され次第、満たされます。
クロスドキュメントの遷移、およびクロスドキュメントの遷移を試みた結果として、204または205のステータス、またはサーバーからの`Content-Disposition: attachment`ヘッダーフィールドにより実際には遷移が行われない場合、両方のプロミスは決して解決されません。
{ committed, finished } = navigation.back(key)
{ committed, finished } = navigation.back(key, { info })
ナビゲーブルが最も近い前のセッション履歴エントリに遷移し、異なるNavigationHistoryEntryに対応してnavigation.currentEntryが変更されるようにします。infoは任意の値に設定でき、対応するinfoプロパティが設定されます。
そのセッション履歴エントリへの遷移が既に進行中である場合、このメソッドはその元の遷移のプロミスを返し、infoは無視されます。
返されたプロミスは、traverseTo()で返されたものと同等の挙動を示します。
{ committed, finished } = navigation.forward(key)
{ committed, finished } = navigation.forward(key, { info })
ナビゲーブルが最も近い前方のセッション履歴エントリに遷移し、異なるNavigationHistoryEntryに対応してnavigation.currentEntryが変更されるようにします。infoは任意の値に設定でき、対応するinfoプロパティが設定されます。
そのセッション履歴エントリへの遷移が既に進行中である場合、このメソッドはその元の遷移のプロミスを返し、infoは無視されます。
返されたプロミスは、traverseTo()で返されたものと同等の挙動を示します。
navigate(url, options)
メソッドの手順は次のとおりです:
urlRecord を、url とthis の 関連設定オブジェクト に基づいて URL を解析 した結果とする。
もし urlRecord が失敗した場合、早期エラー結果 を、"SyntaxError" DOMException
のエラーとして返す。
document を、this の 関連するグローバルオブジェクト の 関連付けられた Document
とする。
もし options["history"]
が "push"
に設定されていて、urlRecord と document に基づいて ナビゲーションが置き換えである必要がある
と判断された場合、早期エラー結果 を、"NotSupportedError" DOMException
のエラーとして返す。
state を、options["state"]
に設定されたものとし、それが 存在する
場合はそのまま、存在しない場合は undefined とする。
serializedState を StructuredSerializeForStorage(state) とする。これが例外をスローした場合、その例外の 早期エラー結果 を返す。
この手順は早期に実行されるべきである。なぜならシリアライズはウェブ開発者のコードを呼び出すことがあり、それが後続の手順でチェックされるさまざまなものを変更する可能性があるからである。
document が 完全にアクティブでない 場合、早期エラー結果 を、"InvalidStateError" DOMException
のエラーとして返す。
document の アンロードカウンタ が 0 より大きい場合、早期エラー結果 を、"InvalidStateError" DOMException
のエラーとして返す。
info を options["info"]
に設定されたものとし、それが 存在する
場合はそのまま、存在しない場合は undefined とする。
apiMethodTracker を、info と serializedState を基に 非トラバース API メソッドトラッカーの設定を行うかどうかを決定する の結果とする。
document の ノードナビゲーブル を urlRecord
にナビゲートし、document を使用して、履歴ハンドリング を options["history"]
に設定し、ナビゲーション API 状態 を serializedState に設定する。
location.assign()
などと異なり、オリジンドメイン 境界を超えて公開されるものでなく、navigation.navigate()
は、この window.navigation
プロパティへの直接同期アクセスを持つコードのみがアクセスできる。そのため、ナビゲーションのソースドキュメントの帰属についての複雑な問題を回避でき、サンドボックスによってナビゲートが許可されているか
のチェックやその付随する 例外有効フラグ の処理は不要となる。我々は、すべてのナビゲーションがこの Navigation
オブジェクト自体に対応する Document
から来るものとして扱うだけでよい(すなわち document から)。
もし this の 非トラバース API メソッドトラッカー が apiMethodTracker である場合は:
非トラバース API
メソッドトラッカー がまだ apiMethodTracker である場合、これは ナビゲート アルゴリズムが 内部
navigate イベント発火アルゴリズム に到達する前に中止されたことを意味する。それにより、この非トラバース API
メソッドトラッカーを進行中に昇格するプロセスが行われなかった。
this の 非トラバース API メソッドトラッカー を null に設定する。
早期エラー結果
を、"AbortError" DOMException
のエラーとして返す。
apiMethodTracker の ナビゲーション API メソッドトラッカーに基づく結果 を返す。
reload(options) メソッドの手順は以下の通りです:
document を this の 関連するグローバルオブジェクト の 関連
Document とします。
serializedState を StructuredSerializeForStorage(undefined) に設定します。
もし options["state"]
が存在する場合は、serializedState を StructuredSerializeForStorage(options["state"])
に設定します。もし例外が発生した場合は、その例外に対する 早期エラー結果 を返します。
この手順を早期に実行することが重要です。シリアライズはウェブ開発者のコードを呼び出す可能性があり、それにより後のステップで確認するさまざまなことが変更されるかもしれません。
その他の場合:
current を 現在のエントリ に設定します。
もし current が null でない場合、serializedState を current の セッション履歴エントリ の ナビゲーションAPIの状態 に設定します。
もし document の アンロードカウンター が 0 より大きい場合は、早期エラー結果 を返します。
info を options["info"]
に設定します。それが存在しない場合は undefined に設定します。
apiMethodTracker を設定する結果を APIメソッドトラッカーの設定を試みる に基づいて返します。
リロード を document の ナビゲーション可能なノード に対して実行します。
APIメソッドトラッカーから派生した結果 を返します。
traverseTo(key, options) メソッドの手順は以下の通りです:
もし this の 現在のエントリインデックス が −1
である場合、早期エラー結果 を "InvalidStateError" DOMException
で返します。
もし this の エントリリスト に、含まれる セッション履歴エントリ の ナビゲーションAPIキー が key
に等しい NavigationHistoryEntry
が存在しない場合、早期エラー結果 を "InvalidStateError" DOMException
で返します。
ナビゲーションAPIトラバーサルを実行 の結果を、this と key および options を使って返します。
back(options) メソッドの手順は以下の通りです:
もし this の 現在のエントリインデックス が −1 または
0 である場合、早期エラー結果 を "InvalidStateError" DOMException
で返します。
key を、this の エントリリスト[this の 現在のエントリインデックス − 1] の セッション履歴エントリ の ナビゲーションAPIキー に設定します。
ナビゲーションAPIトラバーサルを実行 の結果を、this と key および options を使って返します。
forward(options) メソッドの手順は以下の通りです:
もし this の 現在のエントリインデックス が −1 または
this の エントリリスト の サイズ − 1 に等しい場合、早期エラー結果 を "InvalidStateError" DOMException
で返します。
key を this の エントリリスト[this の 現在のエントリインデックス + 1] の セッション履歴エントリ の ナビゲーションAPIキー に設定します。
ナビゲーションAPIトラバーサルを実行 の結果を、this と key および options を使って返します。
ナビゲーションAPIトラバーサルを実行する には、ナビゲーション
navigation、文字列 key、および ナビゲーションオプション
options を使用します:
document を navigation の 関連グローバルオブジェクト の 関連する Document
に設定します。
もし document が 完全にアクティブ でない場合、早期エラー結果 を "InvalidStateError" DOMException
で返します。
もし document の アンロードカウンター が 0 より大きい場合、早期エラー結果 を "InvalidStateError" DOMException
で返します。
current を navigation の 現在のエントリ に設定します。
もし key が current の セッション履歴エントリ の ナビゲーションAPIキー と等しい場合、次のように返します:
«[
"コミット済み"
→ 解決済みの約束 current, "終了済み"
→ 解決済みの約束 current ]».
もし navigation の 予定のトラバースAPIメソッドトラッカー[key] が 存在する 場合、ナビゲーションAPIメソッドトラッカー派生結果 を navigation の 予定のトラバースAPIメソッドトラッカー[key] から返します。
info を options["info"]
に設定します。存在する場合;そうでなければ、undefined に設定します。
apiMethodTracker を 予定のトラバースAPIメソッドトラッカーを追加する の結果から、navigation と key および info を使って設定します。
navigable を document の ナビゲーブルノード に設定します。
traversable を navigable の トラバーサブルナビゲーブル に設定します。
sourceSnapshotParams を ソーススナップショットパラメータのスナップショットを撮る の結果から、document に対して設定します。
traversable に次のセッション履歴トラバース手順を 追加 します:
navigableSHEs を navigable に対して セッション履歴エントリを取得する の結果から設定します。
targetSHE を navigableSHEs の中で、key に等しい ナビゲーションAPIキー を持つ セッション履歴エントリ に設定します。もしそのようなエントリが存在しない場合、次を実行します:
グローバルタスクをキューに追加
し、navigation の 関連グローバルオブジェクト
に対して 終了したプロミスを拒否
し、apiMethodTracker に対して "InvalidStateError" DOMException
で作成します。
これらの手順を中止します。
このパスは、navigation の エントリリスト が navigableSHEs に対して同期される間、履歴の変更に反応してスレッドやプロセスが同期される短期間の間に発生することがあります。
もし targetSHE が navigable の アクティブセッション履歴エントリ である場合、これらの手順を中止します。
これが発生するのは、以前に キューに追加された トラバースがすでにこの セッション履歴エントリ に到達した場合です。その場合、以前のトラバースがすでに apiMethodTracker を処理済みです。
result を、targetSHE の 手順 によって traversable に対して トラバース履歴手順を適用する
の結果から、sourceSnapshotParams、navigable、および "none"
を使って設定します。
もし result が "canceled-by-beforeunload" である場合、グローバルタスクをキューに追加
し、navigation の 関連グローバルオブジェクト に対して 終了したプロミスを拒否
し、apiMethodTracker に対して "AbortError" DOMException
で作成します。
もし result が "initiator-disallowed" である場合、グローバルタスクをキューに追加
し、navigation の 関連グローバルオブジェクト に対して 終了したプロミスを拒否
し、apiMethodTracker に対して "SecurityError" DOMException
で作成します。
結果が "canceled-by-beforeunload" または "initiator-disallowed"
である場合、navigate
イベントは発生しません。進行中のナビゲーションを中止する
は正しくありません。それにより、navigateerror
イベントが発生し、事前の navigate
イベントが存在しません。
"canceled-by-navigate" の場合、navigate
は発生しますが、内部
navigate イベント発火アルゴリズム が 進行中のナビゲーションを中止する
の処理を行います。
apiMethodTracker に対する ナビゲーションAPIメソッドトラッカー派生結果 を返します。
例外 e の早期エラー結果 は、NavigationResult
辞書インスタンスであり、次のように表されます: «[ "committed"
→ 拒否されたプロミス e、 "finished"
→ 拒否されたプロミス e ]»。
ナビゲーションAPIメソッドトラッカー派生結果 は、ナビゲーションAPIメソッドトラッカー
に対するものであり、NavigationResult
辞書インスタンスとして次のように表されます: «[ "committed"
→ apiMethodTracker の コミット済みプロミス、 "finished"
→ apiMethodTracker の 終了済みプロミス ]»。
任意のナビゲーション(広義の意味で)中、Navigationオブジェクトは、次の事項を追跡する必要があります:
| 状態 | 期間 | 説明 |
|---|---|---|
NavigateEvent
|
イベント発火期間中 | ナビゲーションがイベント発火中にキャンセルされた場合、イベントをキャンセルできるようにするため |
| イベントの中止コントローラー | ハンドラから返されるすべてのプロミスが完了するまで | ナビゲーションがキャンセルされた場合に、中止を通知できるようにするため |
| 新しい要素がフォーカスされたかどうか | ハンドラから返されるすべてのプロミスが完了するまで | もしフォーカスがあった場合、フォーカスがリセットされないようにするため |
ナビゲート先のNavigationHistoryEntry
|
ナビゲート先が決定された時から、ハンドラから返されるすべてのプロミスが完了するまで | どのcommittedおよびfinishedプロミスを解決するかを判断するため
|
返されたfinishedプロミス
|
ハンドラから返されるすべてのプロミスが完了するまで | 適切に解決または拒否できるようにするため |
| 状態 | 期間 | 説明 |
|---|---|---|
任意のstate
|
イベント発火期間中 | イベントがキャンセルされずに発火が終了した場合、現在のエントリのナビゲーションAPIステートを更新できるようにするため |
| 状態 | 期間 | 説明 |
|---|---|---|
任意のinfo
|
タスクがnavigateイベントを発火するためにキューに入れられるまで
|
navigateイベントをセッション履歴トラバーサルキューを経て発火するために使用できるようにするため
|
返されたcommittedプロミス
|
セッション履歴が更新されるまで(同じタスク内で) | 適切に解決または拒否できるようにするため |
intercept()が呼び出されたかどうか
|
セッション履歴が更新されるまで(同じタスク内で) | 通常のスクロール復元ロジックを抑制し、scrollオプションで指定された動作に置き換えるため
|
この他にも、次のようなWeb開発者コードが原因で、任意の時点で一度に1つのナビゲーションだけが要求されるとは限りません:
const p1 = navigation. navigate( url1). finished;
const p2 = navigation. navigate( url2). finished;
つまり、このシナリオでは、url2にナビゲートする間もp1のプロミスを保持しておく必要があります。2回目のnavigate()呼び出しが発生した時点で、進行中のナビゲーションプロミスをすぐに削除することはできません。
これを達成するために、各Navigationに次の事項を関連付けます:
進行中のnavigateイベント、NavigateEventまたはnull、初期値はnull
進行中のナビゲーション中にフォーカスが変更されたかどうか、boolean型、初期値はfalse
進行中のナビゲーション中に通常のスクロール復元を抑制するかどうか、boolean型、初期値はfalse
進行中のAPIメソッドトラッカー、ナビゲーションAPIメソッドトラッカーまたはnull、初期値はnull
今後の非「traverse」APIメソッドトラッカー、ナビゲーションAPIメソッドトラッカーまたはnull、初期値はnull
今後の「traverse」APIメソッドトラッカー、ordered map(文字列からナビゲーションAPIメソッドトラッカーへのマッピング)、初期値は空
ここで示されている状態は、ナビゲーションAPIメソッドトラッカーに保存されていないものですが、ナビゲーションAPIメソッドを介して開始されないナビゲーションについても追跡する必要がある状態です。
ナビゲーションAPIメソッドトラッカーとは、次の項目を持つ構造体です:
ナビゲーションオブジェクト、Navigation
キー、文字列またはnull
情報、JavaScriptの値
シリアライズされた状態、シリアライズされた状態またはnull
コミットされたエントリ、NavigationHistoryEntryまたはnull
コミットされたプロミス、プロミス
終了したプロミス、プロミス
この状態は、以下のアルゴリズムによって管理されます。
今後の非「traverse」APIメソッドトラッカーを設定するかどうかを決定するには、Navigation
navigation、JavaScriptの値info、およびシリアライズされた状態またはnullserializedStateを使用します:
committedPromiseおよびfinishedPromiseを、navigationの関連するrealmで新たに作成します。
処理済みとしてマークする finishedPromise。
apiMethodTrackerを新しいナビゲーションAPIメソッドトラッカーとして作成し、以下の項目を設定します:
アサート: navigationの今後の非「traverse」APIメソッドトラッカーがnullであること。
もしnavigationがエントリとイベントが無効になっていない場合は、navigationの今後の非「traverse」APIメソッドトラッカーをapiMethodTrackerに設定します。
もしnavigationがエントリとイベントが無効になっている場合、committedPromiseとfinishedPromiseは決して完了しません(NavigationHistoryEntryオブジェクトがこれらのDocumentに対して作成されないため、これを解決するものが何もないためです)。したがって、このAPIメソッド呼び出しを追跡する必要はありません。
apiMethodTrackerを返します。
次のtraverse APIメソッドトラッカーを追加するには、Navigation
navigation、文字列destinationKeyおよびJavaScriptの値infoを使用します:
committedPromiseおよびfinishedPromiseを、navigationの関連するrealmで新たに作成します。
処理済みとしてマークする finishedPromise。
これが行われる理由については、前述の議論を参照してください。
apiMethodTrackerを新しいナビゲーションAPIメソッドトラッカーとして作成し、以下の項目を設定します:
navigationの次のtraverse APIメソッドトラッカー[key]をapiMethodTrackerに設定します。
apiMethodTrackerを返します。
次のAPIメソッドトラッカーを進行中に昇格するには、Navigation
navigationと文字列またはnullのdestinationKeyを使用します:
アサート: navigationの進行中のAPIメソッドトラッカーがnullであること。
もしdestinationKeyがnullでない場合:
アサート: navigationの次の非traverse APIメソッドトラッカーがnullであること。
もしnavigationの次のtraverse APIメソッドトラッカー[destinationKey]が存在する場合:
navigationの進行中のAPIメソッドトラッカーを、navigationの次のtraverse APIメソッドトラッカー[destinationKey]に設定します。
削除navigationの次のtraverse APIメソッドトラッカー[destinationKey]。
それ以外の場合:
navigationの進行中のAPIメソッドトラッカーを、navigationの次の非traverse APIメソッドトラッカーに設定します。
navigationの次の非traverse APIメソッドトラッカーをnullに設定します。
クリーンアップするには、ナビゲーションAPIメソッドトラッカー apiMethodTrackerを使用します:
navigationをapiMethodTrackerのナビゲーションオブジェクトとして設定します。
もしnavigationの進行中のAPIメソッドトラッカーがapiMethodTrackerである場合は、navigationの進行中のAPIメソッドトラッカーをnullに設定します。
それ以外の場合:
keyをapiMethodTrackerのキーとして設定します。
アサート: keyがnullでないこと。
アサート: navigationの次のtraverse APIメソッドトラッカー[key]が存在すること。
削除 navigationの次のtraverse APIメソッドトラッカー[key]。
コミットされたエントリについて通知するには、ナビゲーションAPIメソッドトラッカー
apiMethodTrackerとNavigationHistoryEntry
nheを使用します:
apiMethodTrackerのコミットされたエントリをnheに設定します。
もしapiMethodTrackerのシリアライズされた状態がnullでない場合は、nheのセッション履歴エントリのナビゲーションAPI状態をapiMethodTrackerのシリアライズされた状態に設定します。
もしnullであれば、navigation.traverseTo()を介してnheに移動しているため、状態を変更することは許可されません。
この時点で、apiMethodTrackerのシリアライズされた状態は不要となります。実装者は、ナビゲーションAPIメソッドトラッカーの存続期間にわたって保持することを避けるために、それをクリアすることを検討するかもしれません。
apiMethodTrackerのコミットされたプロミスをnheで解決します。
この時点で、apiMethodTrackerのコミットされたプロミスは、著者のコードにまだ返されていない場合のみ必要です。実装者は、ナビゲーションAPIメソッドトラッカーの存続期間にわたって保持することを避けるために、それをクリアすることを検討するかもしれません。
終了したプロミスを解決するには、ナビゲーションAPIメソッドトラッカー apiMethodTrackerを使用します:
apiMethodTrackerのコミットされたプロミスを、そのコミットされたエントリで解決します。
通常、コミットされたエントリについて通知するが以前にapiMethodTrackerに対して呼び出されているため、これは何も行いません。ただし、いくつかのケースでは、終了したプロミスを解決するが直接呼び出され、このステップが必要となります。
apiMethodTrackerの終了したプロミスを、そのコミットされたエントリで解決します。
クリーンアップする apiMethodTracker。
終了したプロミスを拒否するには、ナビゲーションAPIメソッドトラッカー apiMethodTrackerとJavaScriptの値exceptionを使用します:
apiMethodTrackerのコミットされたプロミスをexceptionで拒否します。
これは、apiMethodTrackerのコミットされたプロミスが以前にコミットされたエントリについて通知するによって解決された場合、何も行いません。
apiMethodTrackerの終了したプロミスをexceptionで拒否します。
クリーンアップする apiMethodTracker。
進行中のナビゲーションを中止するには、Navigation
navigationおよびオプションのDOMException
errorを使用します:
eventをnavigationの進行中のnavigateイベントとして設定します。
アサート: eventがnullでないこと。
navigationの進行中のナビゲーション中にフォーカスが変更されたをfalseに設定します。
navigationの進行中のナビゲーション中に通常のスクロール復元を抑制するをfalseに設定します。
もしerrorが指定されていない場合、errorを新しい"AbortError" DOMExceptionとして、navigationの関連するrealmで作成します。
navigationの進行中のnavigateイベントをnullに設定します。
errorInfoをerrorからエラー情報を抽出する結果として設定します。
例えば、このアルゴリズムがwindow.stop()の呼び出しによって到達した場合、これらのプロパティはおそらくwindow.stop()を呼び出したスクリプトの行に基づいて初期化されるでしょう。しかし、ユーザーがストップボタンをクリックした場合、これらのプロパティはおそらく空の文字列や0などのデフォルト値で初期化されるでしょう。
イベントを発火する、名前付きnavigateerrorでnavigationに対してErrorEventを使用し、追加属性はerrorInfoに従って初期化されます。
もしnavigationの進行中のAPIメソッドトラッカーがnullでない場合、apiMethodTrackerに対してerrorで終了したプロミスを拒否するを行います。
もしnavigationのトランジションがnullでない場合:
ナビゲーションAPIにナビゲーション中止を通知するには、ナビゲーション可能オブジェクト navigableで行います:
このアルゴリズムがnavigableのアクティブウィンドウの関連エージェントのイベントループで実行されている場合は、次のステップに進みます。それ以外の場合は、グローバルタスクをキューに追加し、navigableのアクティブウィンドウで次のステップを実行します。
navigationをnavigableのアクティブウィンドウのナビゲーションAPIとして設定します。
もしnavigationの進行中のnavigateイベントがnullである場合、終了します。
進行中のナビゲーションを中止する、navigationを指定して。
ナビゲーションAPIに子ナビゲーション可能オブジェクトの破壊を通知するには、ナビゲーション可能オブジェクト navigableを指定します:
ナビゲーションAPIにナビゲーション中止を通知する、navigableで。
navigationをnavigableのアクティブウィンドウのナビゲーションAPIとして設定します。
traversalAPIMethodTrackersをnavigationの今後のトラバースAPIメソッドトラッカーのクローンとして設定します。
各
apiMethodTrackerのtraversalAPIMethodTrackersについて、終了したプロミスを拒否する、apiMethodTrackerに対して、"AbortError"をnavigationの関連するrealmで新たに作成したDOMExceptionで拒否します。
進行中のナビゲーションコンセプトは、最も直接的には、navigation.transitionプロパティを通じてWeb開発者に公開されます。これは、NavigationTransitionインターフェースのインスタンスです:
[Exposed =Window ]
interface NavigationTransition {
readonly attribute NavigationType navigationType ;
readonly attribute NavigationHistoryEntry from ;
readonly attribute Promise <undefined > finished ;
};
navigation.transition
NavigationTransitionで、まだnavigatesuccessやnavigateerrorステージに到達していない進行中のナビゲーションを表します。もし進行中のトランジションがない場合は、nullを返します。
navigation.currentEntry(およびlocation.hrefなどの他のプロパティ)がナビゲーション直後に即座に更新されるため、このnavigation.transitionプロパティは、navigateEvent.intercept()に渡されたハンドラに従って、ナビゲーションが完全に完了していない場合を判断するのに役立ちます。
navigation.transition.navigationType
このトランジションが何のためのナビゲーションであるかを示す、"push"、"replace"、"reload"、または"traverse"のいずれか。
navigation.transition.from
このトランジションが来ているNavigationHistoryEntry。これをnavigation.currentEntryと比較するのに役立ちます。
navigation.transition.finished
navigatesuccessが発火した時点で、またはnavigateerrorイベントが発火した時点で拒否されるプロミス。
各Navigationには、トランジションがあり、これはNavigationTransitionまたはnullであり、最初はnullです。
transitionのゲッターステップは、こののトランジションを返します。
各NavigationTransitionには、ナビゲーションタイプが関連付けられており、これはNavigationTypeです。
各NavigationTransitionには、元のエントリーが関連付けられており、これはNavigationHistoryEntryです。
各NavigationTransitionには、関連する終了したプロミスがあり、これはプロミスです。
navigationTypeのゲッターステップは、こののナビゲーションタイプを返します。
fromのゲッターステップは、このの元のエントリーを返します。
finishedのゲッターステップは、このの終了したプロミスを返します。
NavigationActivation
インターフェース[Exposed =Window ]
interface NavigationActivation {
readonly attribute NavigationHistoryEntry ? from ;
readonly attribute NavigationHistoryEntry entry ;
readonly attribute NavigationType navigationType ;
};
navigation.activation
NavigationActivation
は、最も最近のクロスドキュメントナビゲーションに関する情報を含みます。これは、このDocumentを「アクティベート」したナビゲーションです。
navigation.currentEntryおよびDocumentのURLは、同一ドキュメントナビゲーションにより定期的に更新される可能性がありますが、navigation.activationは固定されており、そのプロパティはDocumentが履歴から再アクティベートされた場合のみ更新されます。
navigation.activation.entry
NavigationHistoryEntryは、navigation.currentEntryプロパティの値と等価であり、Documentがアクティベートされた時点のものです。
navigation.activation.from
NavigationHistoryEntryは、現在のDocumentの直前にアクティブだったDocumentを表します。これがnullの値を持つのは、以前のDocumentがこのドキュメントと同一オリジンでなかった場合、またはそれが最初のabout:blankのDocumentであった場合です。
いくつかのケースでは、fromまたはentryのNavigationHistoryEntryオブジェクトが、traverseTo()メソッドの有効なターゲットではない場合があります。これらは履歴に保持されていないかもしれません。例えば、Documentはlocation.replace()を使用してアクティベートされるか、初期エントリがhistory.replaceState()によって置き換えられた可能性があります。しかし、これらのエントリのurlプロパティとgetState()メソッドは依然としてアクセス可能です。
navigation.activation.navigationType
このDocumentをアクティベートしたナビゲーションの種類を示す、"push"、"replace"、"reload"、または"traverse"のいずれかです。
各Navigationには、関連するアクティベーションがあり、それはnullまたはNavigationActivationオブジェクトであり、最初はnullです。
各NavigationActivationには以下のものがあります:
古いエントリー、nullまたはNavigationHistoryEntry。
新しいエントリー、nullまたはNavigationHistoryEntry。
ナビゲーションタイプ、NavigationType。
activationのゲッターステップは、こののアクティベーションを返します。
fromのゲッターステップは、このの古いエントリーを返します。
entryのゲッターステップは、このの新しいエントリーを返します。
navigationTypeのゲッターステップは、こののナビゲーションタイプを返します。
navigate イベントナビゲーションAPIの主要な機能の一つは、navigate
イベントです。このイベントは、広義の意味でのあらゆるナビゲーションに対して発生し、Web開発者がそのような発信ナビゲーションを監視できるようにします。多くの場合、このイベントはキャンセル可能であり、ナビゲーションが実行されるのを防ぐことができます。また、他の場合では、ナビゲーションをインターセプトし、intercept()
メソッドを使用して、同一ドキュメントナビゲーションに置き換えることができます。
NavigateEvent
インターフェース[Exposed =Window ]
interface NavigateEvent : Event {
constructor (DOMString type , NavigateEventInit eventInitDict );
readonly attribute NavigationType navigationType ;
readonly attribute NavigationDestination destination ;
readonly attribute boolean canIntercept ;
readonly attribute boolean userInitiated ;
readonly attribute boolean hashChange ;
readonly attribute AbortSignal signal ;
readonly attribute FormData ? formData ;
readonly attribute DOMString ? downloadRequest ;
readonly attribute any info ;
readonly attribute boolean hasUAVisualTransition ;
undefined intercept (optional NavigationInterceptOptions options = {});
undefined scroll ();
};
dictionary NavigateEventInit : EventInit {
NavigationType navigationType = "push";
required NavigationDestination destination ;
boolean canIntercept = false ;
boolean userInitiated = false ;
boolean hashChange = false ;
required AbortSignal signal ;
FormData ? formData = null ;
DOMString ? downloadRequest = null ;
any info ;
boolean hasUAVisualTransition = false ;
};
dictionary NavigationInterceptOptions {
NavigationInterceptHandler handler ;
NavigationFocusReset focusReset ;
NavigationScrollBehavior scroll ;
};
enum NavigationFocusReset {
" after-transition " ,
" manual "
};
enum NavigationScrollBehavior {
" after-transition " ,
" manual "
};
callback NavigationInterceptHandler = Promise <undefined > ();
event.navigationType
次のいずれか: "push",
"replace",
"reload",
または "traverse",
これがどのタイプのナビゲーションであるかを示します。
event.destination
ナビゲーションの目的地を表す NavigationDestination
です。
event.canIntercept
このナビゲーションをインターセプトし、通常の動作を置き換えて同一ドキュメント内のナビゲーションに変換できる場合は true、それ以外の場合は false です。
一般的に、現在の Document
が目的地のURLに書き換え可能であれば true ですが、クロスドキュメントの "traverse"
ナビゲーションの場合は常に false となります。
event.userInitiated
このナビゲーションがユーザーが a
要素をクリックしたり、form
要素を送信したり、ブラウザーのUI を使ってナビゲートした結果である場合は true、それ以外の場合は false です。
event.hashChange
フラグメントナビゲーションであれば true、そうでなければ false です。
event.signal
ナビゲーションがキャンセルされた場合、たとえばユーザーがブラウザの「停止」ボタンを押した場合や、別のナビゲーションがこのナビゲーションを中断した場合に中止される AbortSignal
です。
期待されるパターンは、これを開発者が fetch()
などの非同期操作に渡すことです。
event.formData
このナビゲーションが "push"
または "replace"
ナビゲーションであり、フォームの送信を表している場合、このナビゲーションの送信されたフォームエントリを表す
FormData
です。それ以外の場合は null です。
(特に、"reload"
または "traverse"
ナビゲーションが、元々フォームの送信から作成された セッション履歴エントリ を再訪している場合でも、これは null です。)
event.downloadRequest
このナビゲーションが a
または area
要素の download
属性を使用して、ダウンロードとして要求されたかどうかを表します。
ダウンロードが要求されていない場合、このプロパティは null です。
ダウンロードが要求された場合、download
属性の値として提供されたファイル名を返します。(これが空文字列である場合もあります。)
注意すべき点は、ダウンロードが要求されたからといって、必ずしもダウンロードが発生するわけではないことです。たとえば、ダウンロードはブラウザのセキュリティポリシーによってブロックされることがありますし、push
ナビゲーションとして扱われることもあります。
同様に、ダウンロードが要求されていなくても、Content-Disposition: attachment
ヘッダーを持つサーバーの応答によってダウンロードが発生することがあります。
最後に、右クリックしてリンクのターゲットを保存するなどのブラウザUI機能を使用して開始されたダウンロードの場合、navigate
イベントはまったく発生しません。
event.info
このナビゲーションを開始した ナビゲーションAPIメソッド のいずれかを通じて渡された任意のJavaScript値、またはナビゲーションがユーザーまたは他のAPIによって開始された場合は未定義です。
event.hasUAVisualTransition
ユーザーエージェントがこのナビゲーションのために視覚的な遷移を行った場合に true を返します。 true の場合、著者がDOMをポストナビゲーションの状態に同期的に更新することで、最高のユーザーエクスペリエンスが得られます。
event.intercept({ handler, focusReset, scroll })
このナビゲーションをインターセプトし、通常の処理を防ぎ、その代わりに目的地のURLへの同一ドキュメントナビゲーションに変換します。
handler
オプションは、promiseを返す関数にすることができます。handler関数は、navigate
イベントが発生した後に実行され、navigation.currentEntry
プロパティが同期的に更新された後に実行されます。この返されたpromiseは、ナビゲーションの期間、成功、または失敗を示すために使用されます。promiseが解決された後、ブラウザはユーザーにナビゲーションが完了したことを通知します(例:
ローディングスピナーUIや支援技術を通じて)。さらに、アプリケーションの他の部分が応答できるように、適切に navigatesuccess
または navigateerror
イベントが発生します。
デフォルトでは、このメソッドを使用すると、handlerの返されたpromiseが解決されたときにフォーカスがリセットされます。フォーカスは、autofocus
属性が設定された最初の要素、または属性が存在しない場合は body要素 にリセットされます。focusReset
オプションを "manual"
に設定することで、この動作を回避できます。
デフォルトでは、このメソッドを使用すると、"traverse"
または "reload"
ナビゲーションに対するブラウザのスクロール復元ロジック、または "push"
または "replace"
ナビゲーションに対するスクロールリセット/フラグメントへのスクロールロジックを、handlerの返されたpromiseが解決されるまで遅らせます。scroll
オプションを "manual"
に設定して、ブラウザがこのナビゲーションのために行うスクロール動作を完全にオフにするか、promiseが解決される前に scroll()
を呼び出して、この動作を早期にトリガーすることができます。
このメソッドは、"SecurityError"
DOMException
をスローします。canIntercept
が false の場合、または isTrusted
が false の場合にスローされます。また、同期的に呼び出されなかった場合、イベントディスパッチ中に呼び出されなかった場合には、"InvalidStateError" DOMException
をスローします。
event.scroll()
"traverse"
または "reload"
ナビゲーションの場合、ブラウザの通常のスクロール復元ロジックを使用してスクロール位置を復元します。
"push"
または "replace"
ナビゲーションの場合、ドキュメントの上部にスクロール位置をリセットするか、destination.url
で指定されたフラグメントにスクロールします。
複数回呼び出された場合、またはhandlerの返されたpromiseが解決された後に自動的にポストトランジションスクロール処理が行われた場合や、ナビゲーションがコミットされる前に呼び出された場合、このメソッドは"InvalidStateError" DOMException
をスローします。
それぞれの NavigateEvent
は、"none"、"intercepted"、"committed"、"scrolled"、または
"finished" のいずれかである インターセプション状態 を持ち、初期状態は
"none" です。
それぞれの NavigateEvent
は、ナビゲーションハンドラーリストを持ち、これは リストであり、NavigationInterceptHandler
コールバックが含まれ、初期状態は空です。
それぞれの NavigateEvent
は、フォーカスリセットの動作を持ち、これは NavigationFocusReset-or-null
であり、初期状態は null です。
それぞれの NavigateEvent
は、スクロールの動作を持ち、これは NavigationScrollBehavior-or-null
であり、初期状態は null です。
それぞれの NavigateEvent
は、アボートコントローラーを持ち、これは AbortController-or-null
であり、初期状態は null です。
それぞれの NavigateEvent
は、クラシックヒストリーAPI状態を持ち、これは シリアライズされた状態または null
です。これは、イベントの navigationType
が "push"
または "replace"
である場合のみに使用され、イベントが 発生したときに適切に設定されます。
navigationType、destination、canIntercept、userInitiated、hashChange、signal、formData、downloadRequest、info、および hasUAVisualTransition の属性は、それらが初期化された値を返さなければなりません。
intercept(options) メソッドの手順は次のとおりです:
共通のチェックを実行します thisに対して。
もし this の canIntercept
属性が false に初期化されていた場合、"SecurityError" DOMException
をスローします。
もし this の ディスパッチフラグ
が未設定の場合、"InvalidStateError" DOMException
をスローします。
アサート: this の インターセプション状態 が
"none" または "intercepted" であることを確認します。
this の インターセプション状態 を
"intercepted" に設定します。
もし options["handler"]
が 存在する場合、それを this の ナビゲーションハンドラーリスト に
追加します。
もし options["focusReset"]
が 存在する場合、以下を実行します:
もし this の フォーカスリセットの動作 が null
ではなく、かつそれが options["focusReset"]
と等しくない場合、ユーザーエージェントは前回の呼び出しにおける focusReset
オプションの値がこの新しい値によって上書きされたことをコンソールに警告として表示することができます。そして、前回の値は無視されます。
this の フォーカスリセットの動作 を
options["focusReset"]
に設定します。
scroll() メソッドの手順は次のとおりです:
共通のチェックを実行します thisに対して。
もし this の インターセプション状態 が
"committed" でない場合、"InvalidStateError" DOMException
をスローします。
スクロール動作を処理します thisに対して。
次の手順を使用して、NavigateEvent
イベントに対して共通のチェックを実行します:
もし イベント の 関連するグローバルオブジェクト の 関連するDocument が 完全にアクティブでない場合、"InvalidStateError" DOMException
をスローします。
もし イベント の isTrusted
属性が false に初期化されていた場合、"SecurityError" DOMException
をスローします。
もし イベント の キャンセルフラグ
が設定されている場合、"InvalidStateError" DOMException
をスローします。
NavigationDestination
インターフェース[Exposed =Window ]
interface NavigationDestination {
readonly attribute USVString url ;
readonly attribute DOMString key ;
readonly attribute DOMString id ;
readonly attribute long long index ;
readonly attribute boolean sameDocument ;
any getState ();
};
event.destination.url
ナビゲート先のURL。
event.destination.key
ナビゲーションが"traverse"の場合は、目的地のNavigationHistoryEntryのkeyプロパティの値、そうでない場合は空の文字列。
event.destination.id
ナビゲーションが"traverse"の場合は、目的地のNavigationHistoryEntryのidプロパティの値、そうでない場合は空の文字列。
event.destination.index
ナビゲーションが"traverse"の場合は、目的地のNavigationHistoryEntryのindexプロパティの値、そうでない場合は-1。
event.destination.sameDocument
このナビゲーションが現在のDocumentと同じものであるかどうかを示します。これは、例えばフラグメントナビゲーションやhistory.pushState()ナビゲーションの場合にtrueになります。
このプロパティはナビゲーションの元々の性質を示します。クロスドキュメントナビゲーションがnavigateEvent.intercept()を使用して同じドキュメント内のナビゲーションに変換された場合でも、このプロパティの値は変わりません。
event.destination.getState()
"traverse"ナビゲーションの場合、目的地のセッション履歴エントリに保存されている状態をデシリアライズしたものを返します。
"push"または"replace"ナビゲーションの場合、そのナビゲーションがnavigation.navigate()メソッドによって開始されたものであれば、そこに渡された状態のデシリアライズを返し、そうでなければ未定義の値を返します。
"reload"ナビゲーションの場合、そのリロードがnavigation.reload()メソッドによって開始されたものであれば、そこに渡された状態のデシリアライズを返し、そうでなければ未定義の値を返します。
各 NavigationDestination
には URL があり、これは URL です。
各 NavigationDestination
には entry があり、これは NavigationHistoryEntry
か、nullです。
この NavigationDestination
が "traverse"
ナビゲーションに対応する場合に限り、nullではありません。
各 NavigationDestination
には state があり、これは serialized state です。
各 NavigationDestination
には is same document があり、これは boolean です。
url の getter 手順は、this の URL を serialized して返します。
key の getter 手順は次のとおりです:
id の getter 手順は次のとおりです:
index の getter 手順は次のとおりです:
sameDocument の getter 手順は、this の is same document
を返します。
getState() メソッドの手順は、StructuredDeserialize(this の state) を返します。
標準の他の部分は、このセクションで示される一連のラッパーアルゴリズムを通じて、navigate イベントを発火します。
セッション履歴エントリ destinationSHE と、任意の ユーザーのナビゲーション関与度
userInvolvement (デフォルトは "none")が与えられた場合に、traverse navigate イベントを発火するには、次の手順を実行します。
event を イベント作成
の結果として生成します。NavigateEvent、navigation
の 関連する領域 で作成されます。
event の クラシック履歴 API 状態 を null に設定します。
destination を 新しい NavigationDestination
として navigation の 関連する領域 で作成します。
destinationNHE を navigation の エントリリスト の中の NavigationHistoryEntry
に設定し、destinationSHE の セッション履歴エントリ
に関連付けます。関連がない場合は null を設定します。
もし destinationNHE が null でなければ:
destination の エントリ を destinationNHE に設定します。
destination の 状態 を destinationSHE の ナビゲーション API 状態 に設定します。
そうでない場合、
destination の エントリ を null に設定します。
destination の 状態 を StructuredSerializeForStorage(null) に設定します。
destination の is same document を true
に設定します。もし destinationSHE の document が navigation の 関連するグローバルオブジェクト の
関連する
Document に等しい場合、そうでない場合は false に設定します。
navigation に与えられた "traverse"
として、event、destination、userInvolvement、null、および null の結果として、内部 navigate
イベント発火アルゴリズム を実行します。
push/replace/reload navigate
イベントを発火するには、Navigation
navigation に対して、NavigationType navigationType、URL destinationURL、ブール値の isSameDocument、任意の ユーザーのナビゲーション関与 userInvolvement(デフォルトは "none")、任意の エントリリストまたは null の formDataEntryList(デフォルトは null)、任意の シリアライズ状態 navigationAPIState(デフォルトは StructuredSerializeForStorage(null))、および任意の シリアライズ状態または null の classicHistoryAPIState(デフォルトは
null)が与えられる必要があります。
event を イベント作成
の結果として生成します。NavigateEvent、navigation
の 関連する領域 で作成されます。
event の クラシック履歴 API 状態 を classicHistoryAPIState に設定します。
destination を 新しい NavigationDestination
として navigation の 関連する領域 で作成します。
destination の URL を destinationURL に設定します。
destination の エントリ を null に設定します。
destination の 状態 を navigationAPIState に設定します。
destination の is same document を isSameDocument に設定します。
navigation、navigationType、event、destination、userInvolvement、formDataEntryList
および null が与えられた場合に、内部 navigate
イベント発火アルゴリズム を実行し、その結果を返します。
ダウンロード要求 navigate イベントを発火するには、Navigation navigation
に対して、URL
destinationURL、ユーザーのナビゲーション関与
userInvolvement、および文字列 filename が与えられる必要があります。
event を イベント作成
の結果として生成します。NavigateEvent、navigation
の 関連する領域 で作成されます。
event の クラシック履歴 API 状態 を null に設定します。
destination を 新しい NavigationDestination
として navigation の 関連する領域 で作成します。
destination の URL を destinationURL に設定します。
destination の エントリ を null に設定します。
destination の 状態 を StructuredSerializeForStorage(null) に設定します。
destination の is same document を false に設定します。
navigation、"push"、event、destination、userInvolvement、null
および filename が与えられた場合に、内部 navigate
イベント発火アルゴリズム を実行し、その結果を返します。
内部 navigate イベント発火アルゴリズムは、Navigation navigation、NavigationType
navigationType、NavigateEvent
event、NavigationDestination
destination、ユーザーのナビゲーション関与 userInvolvement、エントリリストまたはnullのformDataEntryList、および文字列またはnullのdownloadRequestFilenameを与えられたとき、以下の手順から構成されます。
もしnavigationがエントリおよびイベントを無効にしているならば、次の手順を実行します。
確認します: navigationの進行中のAPIメソッドトラッカーはnullであること。
確認します: navigationの今後の非トラバースAPIメソッドトラッカーはnullであること。
確認します: navigationの今後のトラバースAPIメソッドトラッカーは空であること。
真を返します。
これらの確認は、traverseTo()、back()、およびforward()が、エントリおよびイベントが無効な場合(トラバースするエントリがないため)即座に失敗すること、そしてnavigate()またはreload()が開始地点である場合、設定を避けたためです。
destinationKeyをnullに設定します。
もしdestinationのエントリがnullでない場合は、destinationKeyをdestinationのエントリのキーに設定します。
確認します: destinationKeyが空文字列ではないこと。
今後のAPIメソッドトラッカーを進行中に昇格させます。navigationとdestinationKeyを指定します。
apiMethodTrackerをnavigationの進行中のAPIメソッドトラッカーに設定します。
navigableをnavigationの関連するグローバルオブジェクトのナビゲーション可能に設定します。
documentをnavigationの関連するグローバルオブジェクトの関連付けられたDocumentに設定します。
もしdocumentがそのURLをdestinationのURLに書き換えることができ、かつdestinationの同一ドキュメントが真であるか、navigationTypeが"traverse"でない場合、eventのcanInterceptを真に初期化します。それ以外の場合は偽に初期化します。
次のいずれかの場合:
navigationTypeが"traverse"でない場合。
traverseCanBeCanceledが真の場合。
その場合、eventのcancelableを真に初期化します。それ以外の場合は偽に初期化します。
eventのnavigationTypeをnavigationTypeに初期化します。
eventのdestinationをdestinationに初期化します。
eventのdownloadRequestをdownloadRequestFilenameに初期化します。
もしapiMethodTrackerがnullでない場合、eventのinfoをapiMethodTrackerの情報に初期化します。それ以外の場合は、undefinedに初期化します。
この時点でapiMethodTrackerの情報はもはや必要なく、ナビゲーションAPIメソッドトラッカーのライフタイム全体で保持せずにクリアできます。
ユーザーエージェントによってdocumentの最新のエントリのキャッシュされたレンダリング状態を表示するためのビジュアル遷移が行われた場合、eventのhasUAVisualTransitionを真に初期化します。それ以外の場合は偽に初期化します。
eventの中止コントローラーを、navigationの関連する領域で作成された新しいAbortControllerに設定します。
currentURLをdocumentのURLに設定します。
次のすべてが真である場合:
eventのクラシック履歴APIの状態がnullであること。
destinationの同一ドキュメントが真であること。
その場合、eventのhashChangeを真に初期化します。それ以外の場合は偽に初期化します。
ここでの最初の条件は、hashChangeがフラグメントナビゲーションの場合には真であるが、history.pushState(undefined, "", "#fragment")のようなケースでは偽であることを意味します。
もしuserInvolvementが"none"でない場合、eventのuserInitiatedを真に初期化します。それ以外の場合は偽に初期化します。
もしformDataEntryListがnullでない場合、eventのformDataを、navigationの関連する領域で作成され、formDataEntryListに関連付けられた新しいFormDataに初期化します。それ以外の場合はnullに初期化します。
確認します: navigationの進行中のnavigateイベントはnullであること。
navigationの進行中のnavigateイベントをeventに設定します。
navigationの進行中のナビゲーション中にフォーカスが変更されたを偽に設定します。
navigationの進行中のナビゲーション中の通常のスクロール復元を抑制を偽に設定します。
dispatchResultを、イベントをディスパッチする結果として、eventをnavigationにディスパッチすることによって取得します。
もしdispatchResultが偽の場合:
もしnavigationTypeが"traverse"であるなら、navigationの関連するグローバルオブジェクトを指定して履歴アクションのユーザーアクティベーションを消費する。
もしeventの中止コントローラーのシグナルが中止されていない場合、navigationを指定して進行中のナビゲーションを中止する。
偽を返します。
endResultIsSameDocumentが真である場合、eventのインターセプション状態が"none"でないか、eventのdestinationの同一ドキュメントが真である場合、真に設定します。
スクリプトを実行する準備をします。navigationの関連設定オブジェクトを指定します。
もしeventのインターセプション状態が"none"でない場合:
eventのインターセプション状態を"committed"に設定します。
fromNHEをnavigationの現在のエントリに設定します。
確認します: fromNHEがnullでないこと。
navigationの遷移を、navigationの関連する領域で作成された新しいNavigationTransitionに設定します。このNavigationTransitionのナビゲーションタイプはnavigationTypeに設定され、fromエントリはfromNHEに設定され、終了したプロミスはnavigationの関連する領域で作成された新しいプロミスに設定されます。
ハンドル済みとしてマークされたnavigationの遷移の終了したプロミス。
他の終了したプロミスに関する議論を参照してください。
もしnavigationTypeが"traverse"であるなら、navigationの進行中のナビゲーション中の通常のスクロール復元を抑制に設定します。
もしeventのスクロール動作が"after-transition"に設定されていた場合、スクロール復元は関連するNavigateEventの完了の一部として行われます。それ以外の場合、スクロール復元は行われません。すなわち、intercept()でインターセプトされたナビゲーションは、通常のスクロール復元プロセスを経ることはありません。このようなナビゲーションのスクロール復元は、手動でウェブ開発者が行うか、遷移後に行われます。
もしnavigationTypeが"push"または"replace"である場合、documentとeventのdestinationのURLを指定してURLおよび履歴の更新ステップを実行します。serialiedDataはeventのクラシック履歴API状態に設定され、historyHandlingはnavigationTypeに設定されます。
もしnavigationTypeが"reload"である場合、これは"reload"を"同一ドキュメントのリロード"に変換しています。この場合、URLおよび履歴の更新ステップは適用されません。ナビゲーションAPI関連の処理は引き続き行われ、例えばnavigation.reload()によって引き起こされた場合、アクティブなセッション履歴エントリのナビゲーションAPI状態が更新されます。
もしnavigationTypeが"traverse"である場合、このイベントの発火はトラバース履歴ステップを適用する一部として行われ、そのプロセスが適切なセッション履歴エントリの更新を行います。
もしendResultIsSameDocumentが真である場合:
promisesListを空のリストに設定します。
各handlerに対して、eventのナビゲーションハンドラーリストの:
結果を追加します: コールバック関数を呼び出します。空の引数リストでhandlerをpromisesListに追加します。
もしpromisesListのサイズが0である場合、promisesListを「undefinedで解決されたプロミス」に設定します。
このAPIでは、非常に多くのイベントやプロミスハンドラーがほぼ同時に発生するため、このタイミングの違いは容易に観察できます:
それはイベント/プロミスハンドラーの順序を変動させる可能性があります。関与するイベントやプロミスには、navigatesuccess/navigateerror、currententrychange、dispose、apiMethodTrackerのプロミス、およびnavigation.transition.finishedプロミスなどが含まれます。
全てを待機: promisesListの成功ステップとして:
もしeventの関連するグローバルオブジェクトが完全にアクティブでない場合、これらのステップを中止します。
確認します: eventがnavigationの進行中のnavigateイベントと等しいこと。
navigationの進行中のnavigateイベントをnullに設定します。
完了: eventを真として完了します。
イベントを発火します: navigationでnavigatesuccessという名前のイベントを発火します。
navigationの遷移をnullに設定します。
もしapiMethodTrackerがnullでない場合、終了プロミスを解決します: apiMethodTrackerに対して。
そして、次の失敗ステップをrejectionReasonを理由にして実行します:
もしeventの関連するグローバルオブジェクトが完全にアクティブでない場合、これらのステップを中止します。
確認します: eventがnavigationの進行中のnavigateイベントと等しいこと。
navigationの進行中のnavigateイベントをnullに設定します。
完了: eventを偽として完了します。
errorInfoを、エラー情報を抽出: rejectionReasonから得た結果として設定します。
イベントを発火します: navigationでnavigateerrorという名前のイベントを発火します。追加の属性はerrorInfoに従って初期化します。
もしnavigationの遷移がnullでない場合、navigationの遷移の終了プロミスをrejectionReasonで拒否します。
navigationの遷移をnullに設定します。
もしapiMethodTrackerがnullでない場合、終了プロミスを拒否: rejectionReasonを理由にしてapiMethodTrackerに対して行います。
それ以外の場合、もしapiMethodTrackerがnullでない場合、クリーンアップします: apiMethodTracker。
スクリプト実行後のクリーンアップ: navigationの関連する設定オブジェクトを指定します。
前述のノートに従い、これによりプロミスハンドラーマイクロタスクを抑制することが終了し、それらがこの時点または後で実行されることになります。
もしeventのインターセプション状態が"none"である場合、真を返します。
偽を返します。
navigateEvent.intercept()を呼び出すことで、Web
開発者は同一ドキュメントナビゲーションの通常のスクロールおよびフォーカス動作を抑制し、代わりに後でクロスドキュメントナビゲーションのような動作を実行できます。このセクションのアルゴリズムは、その後適切なタイミングで呼び出されます。
ブール値didFulfillを指定して、NavigateEventをeventとして終了するには、次の手順に従います:
確認: eventのインターセプション状態が
"intercepted" または "finished" でないことを確認します。
もしeventのインターセプション状態が
"none" である場合、終了します。
フォーカスをリセットする可能性をeventに対して実行します。
もしdidFulfillが真であれば、スクロール動作を処理する可能性をeventに対して実行します。
eventのインターセプション状態を
"finished" に設定します。
フォーカスをリセットする可能性を、NavigateEventをeventとして実行するには:
確認: eventのインターセプション状態が
"committed" または "scrolled" であることを確認します。
navigationをeventの関連グローバルオブジェクトのナビゲーションAPIとして設定します。
focusChangedを、navigationの進行中のナビゲーション中にフォーカスが変更されたかとして設定します。
navigationの進行中のナビゲーション中にフォーカスが変更されたかをfalseに設定します。
もしfocusChangedがtrueであれば、終了します。
もしeventのフォーカスリセット動作が "manual"
であれば、終了します。
もしそれがnullのままであれば、それを"after-transition"として扱い、処理を続行します。
documentをeventの関連グローバルオブジェクトの関連ドキュメントとして設定します。
focusTargetをオートフォーカスデリゲートとしてdocumentに設定します。
もしfocusTargetがnullであれば、focusTargetをdocumentのボディ要素に設定します。
もしfocusTargetがnullであれば、focusTargetをdocumentのドキュメント要素に設定します。
フォーカシングステップをfocusTargetに対して実行し、documentのビューポートをフォールバックターゲットとして設定します。
シーケンシャルフォーカスナビゲーション開始点をfocusTargetに移動します。
スクロール動作を処理する可能性を、NavigateEventをeventとして実行するには:
確認: eventのインターセプション状態が
"committed" または "scrolled" であることを確認します。
もしeventのインターセプション状態が
"scrolled" である場合、終了します。
もしeventのスクロール動作が "manual"
である場合、終了します。
もしそれがnullのままであれば、それを"after-transition"として扱い、処理を続行します。
スクロール動作を処理をeventに対して実行します。
スクロール動作を処理を、NavigateEventをeventとして実行するには:
確認: eventのインターセプション状態が
"committed" であることを確認します。
eventのインターセプション状態を
"scrolled" に設定します。
もしeventのナビゲーションタイプが
"traverse"
または "reload"
に初期化されている場合、スクロール位置データを復元し、eventの関連グローバルオブジェクトのナビゲーブルのアクティブセッション履歴エントリを復元します。
それ以外の場合:
documentをeventの関連グローバルオブジェクトの関連ドキュメントとして設定します。
もしdocumentの指定された部分がnullであれば、ドキュメントの先頭にスクロールし、documentに適用します。[CSSOMVIEW]
それ以外の場合、フラグメントにスクロールします。
NavigateEvent
インターフェイスは、その複雑さのため、専用のセクションを持っています。
NavigationCurrentEntryChangeEvent
インターフェイス[Exposed =Window ]
interface NavigationCurrentEntryChangeEvent : Event {
constructor (DOMString type , NavigationCurrentEntryChangeEventInit eventInitDict );
readonly attribute NavigationType ? navigationType ;
readonly attribute NavigationHistoryEntry from ;
};
dictionary NavigationCurrentEntryChangeEventInit : EventInit {
NavigationType ? navigationType = null ;
required NavigationHistoryEntry from ;
};
event.navigationType
現在のエントリが変更された原因となったナビゲーションの種類を返します。変更がnavigation.updateCurrentEntry()による場合はnullを返します。
event.from
現在のエントリが変更される前のnavigation.currentEntryの以前の値を返します。
もしnavigationType
がnullであるか、"reload"である場合、この値はnavigation.currentEntryと同じになります。
この場合、エントリが新しいエントリに移動したり、現在のエントリが置き換えられたりしなくても、エントリの内容が変更されたことを示します。
navigationType およびfrom属性は、初期化された値を返す必要があります。
PopStateEvent
インターフェイス現在のすべてのエンジンでサポートされています。
現在のすべてのエンジンでサポートされています。
[Exposed =Window ]
interface PopStateEvent : Event {
constructor (DOMString type , optional PopStateEventInit eventInitDict = {});
readonly attribute any state ;
readonly attribute boolean hasUAVisualTransition ;
};
dictionary PopStateEventInit : EventInit {
any state = null ;
boolean hasUAVisualTransition = false ;
};
event.state
すべての現行エンジンでサポートされています。
pushState()
または replaceState()
に提供された情報のコピーを返します。
event.hasUAVisualTransition
ユーザーエージェントがこのナビゲーションのためにビジュアルトランジションを実行した場合、trueを返します。trueの場合、作成者がナビゲーション後の状態に同期的にDOMを更新することで、最良のユーザーエクスペリエンスが得られます。
state
属性は、それが初期化された値を返さなければなりません。これはイベントのコンテキスト情報を表すか、状態が Document の初期状態を表す場合はnullを返します。
hasUAVisualTransition 属性も、初期化された値を返さなければなりません。
HashChangeEvent
interfaceHashChangeEvent/HashChangeEvent
すべての現行エンジンでサポートされています。
すべての現行エンジンでサポートされています。
[Exposed =Window ]
interface HashChangeEvent : Event {
constructor (DOMString type , optional HashChangeEventInit eventInitDict = {});
readonly attribute USVString oldURL ;
readonly attribute USVString newURL ;
};
dictionary HashChangeEventInit : EventInit {
USVString oldURL = "";
USVString newURL = "";
};
event.oldURL
すべての現行エンジンでサポートされています。
ウィンドウが以前に移動していたURLを返します。
event.newURL
すべての現行エンジンでサポートされています。
ウィンドウが移動している新しいURLを返します。
oldURL
属性は、初期化された値を返さなければなりません。これはイベントのコンテキスト情報を表し、特に以前に移動していた
セッション履歴エントリの
URL を表します。
newURL
属性は、初期化された値を返さなければなりません。これはイベントのコンテキスト情報を表し、特に現在移動している
セッション履歴エントリの
URL を表します。
PageSwapEvent
インターフェース
[Exposed =Window ]
interface PageSwapEvent : Event {
constructor (DOMString type , optional PageSwapEventInit eventInitDict = {});
readonly attribute NavigationActivation ? activation ;
readonly attribute ViewTransition ? viewTransition ;
};
dictionary PageSwapEventInit : EventInit {
NavigationActivation ? activation = null ;
ViewTransition ? viewTransition = null ;
};
event.activation
ナビゲーションアクティベーションオブジェクトは、クロスドキュメントナビゲーションの行き先とタイプを表します。クロスオリジンナビゲーションの場合、この値はnullとなります。
event.activation.entry
ナビゲーション履歴エントリーは、アクティブになろうとしているドキュメントを表します。
event.activation.from
ナビゲーション履歴エントリーは、イベントが発生した瞬間のnavigation.currentEntryプロパティの値と同等です。
event.activation.navigationType
ページスワップを引き起こそうとしているナビゲーションのタイプを示す"プッシュ","リプレイス",
"リロード",
または"トラバース"のいずれかです。
event.viewTransition
イベントが発生したときにアクティブなクロスドキュメントビュー遷移がある場合、アウトバウンドクロスドキュメントビュー遷移を表すViewTransitionオブジェクトを返します。そうでない場合、nullを返します。
activation属性とviewTransition属性は、初期化された値を返す必要があります。
PageRevealEventインターフェース[Exposed =Window ]
interface PageRevealEvent : Event {
constructor (DOMString type , optional PageRevealEventInit eventInitDict = {});
readonly attribute ViewTransition ? viewTransition ;
};
dictionary PageRevealEventInit : EventInit {
ViewTransition ? viewTransition = null ;
};
event.viewTransition
イベントが発生したときにアクティブなインバウンドクロスドキュメントビュー遷移がある場合、ViewTransitionオブジェクトを返します。そうでない場合、nullを返します。
viewTransition属性は初期化された値を返す必要があります。
PageTransitionEventインターフェースPageTransitionEvent/PageTransitionEvent
現在のすべてのエンジンでサポートされています。
現在のすべてのエンジンでサポートされています。
[Exposed =Window ]
interface PageTransitionEvent : Event {
constructor (DOMString type , optional PageTransitionEventInit eventInitDict = {});
readonly attribute boolean persisted ;
};
dictionary PageTransitionEventInit : EventInit {
boolean persisted = false ;
};
event.persisted
すべての現行エンジンでサポートされています。
pageshow
イベントでは、ページが新たに読み込まれている場合は false を返します (その場合は load
イベントが発生します)。それ以外の場合は true を返します。
pagehide
イベントでは、ページが最後に削除される場合は false を返します。それ以外の場合は true を返し、ユーザーがこのページに戻った場合にページが再利用される可能性があることを示します (もし Document の salvageable 状態が true のままであれば)。
ページが再利用できなくなる要因には次のものがあります:
ユーザーエージェントが Document を セッション履歴エントリ 内で アンロード
した後に保持しないことを決定した場合
iframe
が salvageable でない場合
アクティブな WebSocket
オブジェクトが存在する場合
persisted属性は、初期化された値を返す必要があります。これはイベントのコンテキスト情報を表します。
eventNameという名前のページ遷移イベントを発生させるためには、Window
windowに対してpersistedというブール値を持つイベントを発生させます。使用するイベントはPageTransitionEventで、persisted属性をpersistedで初期化し、cancelable属性をtrueに、bubbles属性をtrueに初期化し、legacy
target override flagをセットします。
cancelableおよびbubblesの値は意味を持ちません。イベントのキャンセルは何も行わず、Windowオブジェクトを超えてバブルすることはできないからです。これらは歴史的な理由でtrueに設定されています。
BeforeUnloadEvent
インターフェイス現在のすべてのエンジンでサポートされています。
[Exposed =Window ]
interface BeforeUnloadEvent : Event {
attribute DOMString returnValue ;
};
BeforeUnloadEventに特有の初期化メソッドはありません。
BeforeUnloadEventインターフェイスはレガシーインターフェイスであり、イベントのキャンセルだけでなく、returnValue属性に空文字列以外の値を設定することによっても、アンロードがキャンセルされたかどうかの確認を制御できます。著者はpreventDefault()メソッドや他のイベントキャンセル手段を使用するべきであり、returnValueの使用は避けるべきです。
returnValue属性は、アンロードがキャンセルされたかどうかの確認のプロセスを制御します。イベントが作成されるとき、この属性は空文字列に設定されなければなりません。取得時には最後に設定された値を返し、設定時には新しい値に設定されなければなりません。
この属性は歴史的な理由でDOMStringになっています。空文字列以外の値はすべて、ユーザーに確認を求めるリクエストとして扱われます。
NotRestoredReasonsインターフェイス[Exposed =Window ]
interface NotRestoredReasonDetails {
readonly attribute DOMString reason ;
[Default ] object toJSON ();
};
[Exposed =Window ]
interface NotRestoredReasons {
readonly attribute DOMString ? src ;
readonly attribute DOMString ? id ;
readonly attribute DOMString ? name ;
readonly attribute DOMString ? url ;
readonly attribute FrozenArray <NotRestoredReasonDetails >? reasons ;
readonly attribute FrozenArray <NotRestoredReasons >? children ;
[Default ] object toJSON ();
};
notRestoredReasonDetails.reason
文書が前進/後退キャッシュから提供されなかった理由を説明する文字列を返します。可能な文字列値については、bfcacheブロッキングの詳細の定義を参照してください。
notRestoredReasons.src
文書のノードナビゲーブルのコンテナのsrc属性を返します(それがiframe要素である場合)。設定されていないか、またはそれがiframe要素でない場合、nullを返します。
notRestoredReasons.id
文書のノードナビゲーブルのコンテナのid属性を返します(それがiframe要素である場合)。設定されていないか、またはそれがiframe要素でない場合、nullを返します。
notRestoredReasons.name
文書のノードナビゲーブルのコンテナのname属性を返します(それがiframe要素である場合)。設定されていないか、またはそれがiframe要素でない場合、nullを返します。
notRestoredReasons.url
文書のURLを返します。ただし、文書がクロスオリジンのiframe内にある場合はnullを返します。これは、元のsrcが設定されて以来、iframeがナビゲートされた可能性があるため、srcに加えて報告されます。
notRestoredReasons.reasons
文書に関するNotRestoredReasonDetailsの配列を返します。文書がクロスオリジンのiframe内にある場合は、nullを返します。
notRestoredReasons.children
文書の子に関するNotRestoredReasonsの配列を返します。文書がクロスオリジンのiframe内にある場合は、nullを返します。
NotRestoredReasonDetailsオブジェクトには、バック構造があり、最初はnullで、not restored reason detailsまたはnullが格納されます。
reasonのゲッターステップは、thisのバック構造のreasonを返します。
NotRestoredReasonDetailsオブジェクトを作成するには、not restored reason detailsのbackingStructとrealmのrealmを使用します:
notRestoredReasonDetailsを新しいNotRestoredReasonDetailsオブジェクトとしてrealm内で作成します。
notRestoredReasonDetailsのバック構造をbackingStructに設定します。
notRestoredReasonDetailsを返します。
not restored reason detailsは、次の項目を持つ構造体です:
reason、文字列、初期状態は空。
理由は、ページが前進/後退キャッシュから復元されなかった理由を表す文字列です。文字列は以下のいずれかです。
fetch"
Documentによって開始されたフェッチがまだ進行中であり、キャンセルされたため、ページは安定した状態になく、前進/後退キャッシュに保存できませんでした。
navigation-failure"
Documentを作成した元のナビゲーションにエラーが発生したため、エラードキュメントを前進/後退キャッシュに保存することができませんでした。
parser-aborted"
Documentの最初のHTML解析が完了しなかったため、未完成の文書を前進/後退キャッシュに保存することができませんでした。
websocket"
WebSocket接続がシャットダウンされたため、ページは安定した状態になく、前進/後退キャッシュに保存できませんでした。[WEBSOCKETS]
lock"
masked"
Documentにはクロスオリジンのiframe内に子要素があり、それらが前進/後退キャッシュを妨げた。または、このDocumentがユーザーエージェント固有の理由で前進/後退キャッシュに保存できなかった。
NotRestoredReasons
オブジェクトはバックアップ構造体、未復元の理由またはnullを持ち、初期値はnullです。
NotRestoredReasons
オブジェクトは理由の配列、FrozenArray<またはnullを持ち、初期値はnullです。
NotRestoredReasonDetails>
NotRestoredReasons
オブジェクトは子供の配列、FrozenArray<NotRestoredReasons>またはnullを持ち、初期値はnullです。
srcのgetterのステップは、thisのバックアップ構造体のsrcを返します。
idのgetterのステップは、thisのバックアップ構造体のidを返します。
nameのgetterのステップは、thisのバックアップ構造体のnameを返します。
urlのgetterのステップは次のとおりです:
reasonsのgetterのステップは、thisの理由の配列を返します。
childrenのgetterのステップは、thisの子供の配列を返します。
NotRestoredReasonsオブジェクトを作成するには、未復元の理由のバックアップ構造体とrealmを指定します。
notRestoredReasonsを新しいNotRestoredReasonsオブジェクトとしてrealmで作成します。
notRestoredReasonsのバックアップ構造体をbackingStructに設定します。
もしbackingStructの理由がnullなら、notRestoredReasonsの理由の配列をnullに設定します。
それ以外の場合:
reasonsArrayを空のリストとして設定します。
それぞれのreasonに対して、backingStructの理由を反復します:
NotRestoredReasonDetailsオブジェクトを作成するには、reasonとrealmを指定し、それをreasonsArrayに追加します。
notRestoredReasonsの理由の配列を、frozen arrayを作成することによって得られた結果に設定します。
もしbackingStructの子供がnullなら、notRestoredReasonsの子供の配列をnullに設定します。
それ以外の場合:
childrenArrayを空のリストとして設定します。
それぞれのchildに対して、backingStructの子供を反復します:
NotRestoredReasonsオブジェクトを作成するには、childとrealmを指定し、それをchildrenArrayに追加します。
notRestoredReasonsの子供の配列を、frozen arrayを作成することによって得られた結果に設定します。
notRestoredReasonsを返します。
未復元の理由は、次の構造体である:
src、文字列またはnull、初期値はnull。
id、文字列またはnull、初期値はnull。
name、文字列またはnull、初期値はnull。
url、URLまたはnull、初期値はnull。
Documentの未復元の理由は、そのノードナビゲーブルのアクティブセッション履歴エントリのドキュメント状態の未復元の理由であり、Documentのノードナビゲーブルが最上位のトラバース可能である場合に限ります。それ以外の場合はnullです。
この標準には、ドキュメントのシーケンスをグループ化するためのいくつかの関連する概念が含まれています。簡潔で非規範的な要約として:
ナビゲーブルは、ドキュメントのシーケンスのユーザー向けの表現です。つまり、ドキュメント間をナビゲートできるものを表します。典型的な例として、ウェブブラウザのタブやウィンドウ、iframeやフレーム、フレームセット内のフレームが挙げられます。
トラバース可能なナビゲーブルは、特別なタイプのナビゲーブルで、自分自身およびその子孫のナビゲーブルのセッション履歴を管理します。つまり、自身のドキュメントのシーケンスに加えて、さらに別のドキュメントのシーケンスのツリーを表し、このツリーをフラット化したビューを線形に戻ったり進んだりする能力も持っています。
ブラウジングコンテキストは、開発者向けのドキュメントのシーケンスの表現です。これらはWindowProxyオブジェクトと1対1で対応します。各ナビゲーブルは、特定の定義された状況下での切り替えを伴って、一連のブラウジングコンテキストを提供することができます。
この標準の大部分はナビゲーブルの言語で動作しますが、特定のAPIはブラウジングコンテキストの切り替えを明らかにし、そのため標準の一部はブラウジングコンテキストの用語で動作する必要があります。
ナビゲーブルは、アクティブなセッション履歴エントリを介して、ユーザーにDocumentを提示します。各ナビゲーブルには以下のものがあります:
ID、新しい一意の内部値。
親、ナビゲーブルまたはnull。
現在のセッション履歴エントリ、セッション履歴エントリ。
これは、親のトラバース可能なナビゲーブルのセッション履歴トラバーサルキュー内でのみ変更可能です。
アクティブなセッション履歴エントリ、セッション履歴エントリ。
これは、アクティブなセッション履歴エントリのドキュメントのイベントループからのみ変更可能です。
閉じているかどうかのブール値、初期値はfalse。
これは、最上位のトラバース可能なナビゲーブルに対してのみtrueに設定されます。
ロードイベントを遅延させているかどうかのブール値、初期値はfalse。
これは、ナビゲーブルの親がnullでない場合にのみtrueに設定されます。
現在のセッション履歴エントリとアクティブなセッション履歴エントリは通常同じですが、以下の状況で同期が取れなくなります:
同期ナビゲーションが実行される場合。これにより、アクティブなセッション履歴エントリが一時的に現在のセッション履歴エントリより先に進みます。
履歴ステップの適用時に非表示、非エラーの応答が受信される場合。これにより現在のセッション履歴エントリが更新されますが、アクティブなセッション履歴エントリはそのままです。
ナビゲーブルのアクティブなドキュメントは、アクティブなセッション履歴エントリのドキュメントです。
これは、ナビゲーブルの最上位のトラバース可能のセッション履歴トラバーサルキュー内で安全に読み取ることができます。ナビゲーブルのアクティブな履歴エントリは同期的に変更されることがありますが、新しいエントリは常に同じDocumentを持つことになります。
ナビゲーブルのアクティブなブラウジングコンテキストは、そのアクティブなドキュメントのブラウジングコンテキストです。このナビゲーブルがトラバース可能なナビゲーブルである場合、そのアクティブなブラウジングコンテキストは最上位のブラウジングコンテキストになります。
ナビゲーブルのアクティブなWindowProxyは、そのアクティブなブラウジングコンテキストに関連付けられたWindowProxyです。
ナビゲーブルのアクティブなウィンドウは、そのアクティブなWindowProxyの[[Window]]です。
これは常にナビゲーブルのアクティブなドキュメントの関連グローバルオブジェクトと等しくなります。これはアクティブ化アルゴリズムによって同期されます。
ナビゲーブルのターゲット名は、そのアクティブなセッション履歴エントリのドキュメント状態のナビゲーブルターゲット名です。
nodeのノードナビゲーブルを取得するには、nodeのノードに関連するナビゲーブルで、アクティブなドキュメントが nodeのノードドキュメントであるものを返します。該当する ナビゲーブルがない場合はnullを返します。
ナビゲーブルを初期化するには、navigable、ドキュメント状態、およびオプションでparent(デフォルトはnull)を指定します:
entryを新しいセッション履歴エントリとして設定します:
このアルゴリズムの呼び出し元は、entryのステップを初期化する責任があります。完了するまで「pending」のままになります。
navigableの現在のセッション履歴エントリをentryに設定します。
navigableのアクティブなセッション履歴エントリをentryに設定します。
navigableの親をparentに設定します。
トラバース可能なナビゲーブルは、ナビゲーブルであり、セッション履歴エントリの中から、現在のセッション履歴エントリとアクティブなセッション履歴エントリとして自分自身およびその子孫ナビゲーブルに対してどれを選ぶべきかを制御します。
ナビゲーブルのプロパティに加えて、トラバース可能なナビゲーブルは次のものを持ちます:
現在のセッション履歴ステップ、数値、初期値は0。
セッション履歴トラバーサルキュー、セッション履歴トラバーサル並列キュー、新しいセッション履歴トラバーサル並列キューを開始するの結果。
ネストされた履歴ステップの適用を実行中のブール値、初期値はfalse。
システムの可視状態、"hidden"または"visible"のいずれか。
この項目の要件については、ページの可視性セクションを参照してください。
ナビゲーブルinputNavigableのトラバース可能なナビゲーブルを取得するには:
navigableをinputNavigableに設定します。
navigableがトラバース可能なナビゲーブルでない限り、navigableをnavigableの親に設定します。
navigableを返します。
最上位のトラバース可能なナビゲーブルは、トラバース可能なナビゲーブルであり、親がnullです。
現在、すべてのトラバース可能なナビゲーブルは最上位のトラバース可能なナビゲーブルです。将来の提案では、最上位でないトラバース可能なナビゲーブルの導入が検討されています。
ユーザーエージェントは、最上位のトラバース可能なナビゲーブルセット(セット、最上位のトラバース可能なナビゲーブル)を保持します。これらは通常、ブラウザウィンドウやブラウザタブの形でユーザーに提示されます。
ナビゲーブルinputNavigableの最上位のトラバース可能なナビゲーブルを取得するには:
新しい最上位のトラバース可能なナビゲーブルを作成するには、ブラウジングコンテキストまたはnullのopener、文字列のtargetName、およびオプションのナビゲーブルopenerNavigableForWebDriverを指定します:
documentをnullに設定します。
もしopenerがnullであれば、documentを新しい最上位のブラウジングコンテキストとドキュメントを作成するの第2の戻り値に設定します。
それ以外の場合は、documentを新しい補助ブラウジングコンテキストとドキュメントを作成するの第2の戻り値に設定します。
documentStateを新しいドキュメント状態に設定し、次のプロパティを持たせます:
traversableを新しいトラバース可能なナビゲーブルとして設定します。
ナビゲーブルを初期化する traversableにdocumentStateを指定して初期化します。
initialHistoryEntryをtraversableのアクティブなセッション履歴エントリとして設定します。
initialHistoryEntryのステップを0に設定します。
追加します initialHistoryEntryをtraversableのセッション履歴エントリに。
もしopenerがnullでない場合、トラバース可能なストレージシェッドをレガシークローンするをopenerの最上位のトラバース可能なナビゲーブルおよびtraversableに対して行います。[STORAGE]
追加しますtraversableをユーザーエージェントの最上位のトラバース可能なナビゲーブルセットに。
WebDriver BiDiナビゲーブルが作成されましたをtraversableとopenerNavigableForWebDriverで呼び出します。
traversableを返します。
新しい最上位のトラバース可能なナビゲーブルを作成するには、URL initialNavigationURLおよびオプションのPOSTリソースまたはnullのinitialNavigationPostResource(デフォルトはnull)を指定します:
traversableを新しい最上位のトラバース可能なナビゲーブルを作成するの結果として設定し、nullおよび空の文字列を指定します。
ナビゲート traversableにinitialNavigationURLを使用して、traversableのアクティブなドキュメントに対して行い、documentResourceをinitialNavigationPostResourceに設定します。
これらの初期ナビゲーションは、すべての関連するセキュリティチェックが通過することを確実にするために、traversable自体をナビゲートするものとして扱います。
traversableを返します。
特定の要素(例えば、iframe要素)は、ユーザーにナビゲーブルを提示することができます。これらの要素はナビゲーブルコンテナと呼ばれます。
各ナビゲーブルコンテナには、コンテンツナビゲーブルがあり、それはナビゲーブルまたはnullのいずれかです。初期値はnullです。
ナビゲーブルnavigableのコンテナは、そのナビゲーブルコンテナのコンテンツナビゲーブルがnavigableである要素、またはそのような要素がない場合はnullです。
ナビゲーブルnavigableのコンテナドキュメントを取得するには、以下の手順を実行します:
もしnavigableのコンテナがnullであれば、nullを返します。
navigableのコンテナのノードドキュメントを返します。
これは、navigableのコンテナがシャドウを含むルートと等しいことになります。なぜなら、navigableのコンテナは接続された状態でなければならないからです。
Documentdocumentのコンテナドキュメントを取得するには、以下の手順を実行します:
もしdocumentのノードナビゲーブルがnullであれば、nullを返します。
documentのノードナビゲーブルのコンテナドキュメントを返します。
ナビゲーブルnavigableが別のナビゲーブルpotentialParentの子ナビゲーブルである場合、navigableの親がpotentialParentです。また、ナビゲーブルが「子ナビゲーブルである」と言うこともでき、それはその親がnullでないことを意味します。
すべての子ナビゲーブルは、そのコンテナのコンテンツナビゲーブルです。
ナビゲーブルコンテナcontainerのコンテンツドキュメントを取得するには、以下の手順を実行します:
もしcontainerのコンテンツナビゲーブルがnullであれば、nullを返します。
documentをcontainerのコンテンツナビゲーブルのアクティブなドキュメントとして設定します。
もしdocumentのオリジンと、containerのノードドキュメントのオリジンが同一オリジンドメインでない場合、nullを返します。
documentを返します。
ナビゲーブルコンテナcontainerのコンテンツウィンドウを取得するには、以下の手順を実行します:
もしcontainerのコンテンツナビゲーブルがnullであれば、nullを返します。
containerのコンテンツナビゲーブルのアクティブなWindowProxyのオブジェクトを返します。
要素elementを指定して新しい子ナビゲーブルを作成するには:
parentNavigableをelementのノードナビゲーブルに設定します。
groupをelementのノードドキュメントのブラウジングコンテキストの最上位ブラウジングコンテキストのグループに設定します。
browsingContextとdocumentを、elementのノードドキュメント、element、およびgroupを指定して新しいブラウジングコンテキストとドキュメントを作成するの結果に設定します。
targetNameをnullに設定します。
もしelementがnameコンテンツ属性を持つ場合、targetNameをその属性の値に設定します。
documentStateを新しいドキュメント状態に設定し、次のプロパティを持たせます:
navigableを新しいナビゲーブルに設定します。
ナビゲーブルを初期化する navigableにdocumentStateとparentNavigableを指定して初期化します。
elementのコンテンツナビゲーブルをnavigableに設定します。
historyEntryをnavigableのアクティブなセッション履歴エントリに設定します。
traversableをparentNavigableのトラバース可能なナビゲーブルに設定します。
次のセッション履歴トラバーサルステップを追加するをtraversableに対して実行します:
parentDocStateをparentNavigableのアクティブなセッション履歴エントリのドキュメント状態に設定します。
parentNavigableEntriesをparentNavigableに対してセッション履歴エントリを取得する結果に設定します。
targetStepSHEをparentNavigableEntriesの中で最初のセッション履歴エントリで、parentDocStateと等しいドキュメント状態を持つものに設定します。
nestedHistoryを新しいネストされた履歴として設定し、そのIDをnavigableのIDに、エントリリストを « historyEntry » に設定します。
ナビゲーブルの作成/破棄のための更新をtraversableに対して実行します。
WebDriver BiDiナビゲーブルが作成されましたをtraversableで呼び出します。
ナビゲーブルやそのセッション履歴エントリのシーケンスを視覚化するための便利な方法が、Jake ダイアグラムです。典型的なJake ダイアグラムは以下のようになります:
| 0 | 1 | 2 | 3 | 4 | |
|---|---|---|---|---|---|
top
| /t-a | /t-a#foo | /t-b | ||
frames[0]
| /i-0-a | /i-0-b | |||
frames[1]
| /i-1-a | /i-1-b | |||
ここで、各番号付きの列はトラバース可能なナビゲーブルのセッション履歴ステップの可能な値を示しています。各ラベル付きの行は、異なるURLやドキュメント間を移行するナビゲーブルを描写しています。最初の行にラベルが付いているtopは最上位のトラバース可能なナビゲーブルであり、その他の行は子ナビゲーブルです。各セルの背景色は、そのナビゲーブルにおける新しいドキュメントを示しており、新しい背景色が新しいドキュメントを示します。URLはセルのテキスト内容で示されており、通常、簡潔さのために相対URLとして示されますが、特にクロスオリジンのケースが調査されている場合を除きます。特定のナビゲーブルが特定のステップで存在しない場合、そのセルは空になります。太字斜体のステップ番号は、トラバース可能なナビゲーブルの現在のセッション履歴ステップを示しており、太字斜体のURLを持つすべてのセルは、その行のナビゲーブルの現在のセッション履歴エントリを表します。
したがって、上記のJake ダイアグラムは以下の一連のイベントを示しています:
最上位のトラバース可能なナビゲーブルが作成され、URL /t-a
で開始され、2つの子ナビゲーブルがそれぞれ
/i-0-a および /i-1-a で開始されます。
最初の子ナビゲーブルが別のドキュメントにナビゲートされ、URL /i-0-b
が設定されます。
2番目の子ナビゲーブルが別のドキュメントにナビゲートされ、URL
/i-1-b が設定されます。
最上位のトラバース可能なナビゲーブルが同じドキュメントにナビゲートされ、URL が
/t-a#foo に更新されます。
最上位のトラバース可能なナビゲーブルが別のドキュメントにナビゲートされ、URL が
/t-b に設定されます。(このドキュメントには、当然、古いドキュメントの子ナビゲーブルは引き継がれません。)
トラバース可能なナビゲーブルがデルタで履歴をトラバースし、ステップ1に戻ります。
Jake ダイアグラムは、複数のナビゲーブル、ナビゲーション、およびトラバースの相互作用を視覚化するための強力なツールです。すべての相互作用を捉えることはできませんが(たとえば、ネストのレベルが1つしかない)、この標準のいくつかの複雑な状況を説明するために使用する機会があります。
Jake ダイアグラムは、その創作者である比類なきJake Archibaldにちなんで名付けられました。
ナビゲーブルのコレクションを、特定のDocumentから開始して確認することは、この標準のアルゴリズムにおいて役立つことがよくあります。このセクションでは、これらのナビゲーブルを収集するための厳選されたアルゴリズムが含まれています。
これらのアルゴリズムの戻り値は、親が子の前に表示されるように順序付けられています。呼び出し元はこの順序に依存しています。
Documentから開始することは、ナビゲーブルから開始するよりも一般的には良いことであり、呼び出し元が完全にアクティブなDocumentから開始するかどうかを認識できるようにします。非完全にアクティブなDocumentも親や子孫のナビゲーブルを持つことがありますが、それらはしばしば存在しないかのように振る舞います(例えば、window.parentゲッターにおいて)。
Documentdocumentの祖先ナビゲーブルは、以下の手順で取得します:
ancestorsを空のリストに設定します。
navigableがnullでない限り:
リストの先頭に追加するnavigableをancestorsに。
navigableをnavigableの親に設定します。
ancestorsを返します。
Documentdocumentの包含する祖先ナビゲーブルは、以下の手順で取得します:
Documentdocumentの子孫ナビゲーブルは、以下の手順で取得します:
navigablesを新しいリストに設定します。
navigableContainersをdocumentのすべてのシャドウを含む子孫のナビゲーブルコンテナのリストに設定し、シャドウを含むツリー順序で並べ替えます。
それぞれに対して実行するnavigableContainerをnavigableContainersに含まれる:
もしnavigableContainerのコンテンツナビゲーブルがnullであれば、続行します。
拡張するnavigablesをnavigableContainerのコンテンツナビゲーブルのアクティブなドキュメントの包含する子孫ナビゲーブルで。
navigablesを返します。
Documentdocumentの包含する子孫ナビゲーブルは、以下の手順で取得します:
これらの子孫収集アルゴリズムは、子孫のDocumentオブジェクトのDOMツリーを調べるものとして記述されています。実際には、アルゴリズムの呼び出し元が別のプロセスにある場合、これを実行するのはしばしば不可能です。その代わりに、実装では通常、適切なツリーをプロセス間でレプリケートします。
Documentdocumentのドキュメントツリー子ナビゲーブルは、以下の手順で取得します:
もしdocumentのノードナビゲーブルがnullであれば、空のリストを返します。
navigablesを新しいリストに設定します。
navigableContainersをdocumentのすべての子孫のナビゲーブルコンテナのリストに設定し、ツリー順序で並べ替えます。
それぞれに対して実行するnavigableContainerをnavigableContainersに含まれる:
もしnavigableContainerのコンテンツナビゲーブルがnullであれば、続行します。
追加するnavigableContainerのコンテンツナビゲーブルをnavigablesに。
navigablesを返します。
子ナビゲーブルを破棄するには、ナビゲーブルコンテナcontainerを指定して次の手順を実行します:
navigableをcontainerのコンテンツナビゲーブルに設定します。
もしnavigableがnullであれば、終了します。
containerのコンテンツナビゲーブルをnullに設定します。
ナビゲーションAPIに子ナビゲーブルの破棄を通知するをnavigableを指定して実行します。
ドキュメントとその子孫を破棄するをnavigableのアクティブなドキュメントを指定して実行します。
parentDocStateをcontainerのノードナビゲーブルのアクティブなセッション履歴エントリのドキュメント状態に設定します。
削除するparentDocStateのネストされた履歴から、ネストされた履歴のIDがnavigableのIDと等しいものを。
traversableをcontainerのノードナビゲーブルのトラバース可能なナビゲーブルに設定します。
次のセッション履歴トラバーサルステップを追加するをtraversableに対して実行します:
ナビゲーブルの作成/破棄のための更新をtraversableを指定して実行します。
WebDriver BiDiナビゲーブルが破棄されましたをnavigableで呼び出します。
トップレベルのトラバース可能なナビゲーブルを破棄するには、トップレベルのトラバース可能なナビゲーブルtraversableを指定して次の手順を実行します:
browsingContextをtraversableのアクティブなブラウジングコンテキストに設定します。
それぞれに対して実行するtraversableのセッション履歴エントリに含まれるhistoryEntryをどの順序で?:
documentをhistoryEntryのドキュメントに設定します。
もしdocumentがnullでなければ、ドキュメントとその子孫を破棄するをdocumentを指定して実行します。
削除するbrowsingContextを。
traversableをユーザーインターフェースから削除します(例:タブブラウザーのタブを閉じるまたは非表示にする)。
削除するtraversableをユーザーエージェントのトップレベルのトラバース可能なナビゲーブルセットから。
WebDriver BiDiナビゲーブルが破棄されましたをtraversableで呼び出します。
ユーザーエージェントは、トップレベルのトラバース可能なナビゲーブルを破棄することができます(通常はユーザーの要求に応じて)。
トップレベルのトラバース可能なナビゲーブルtraversableを閉じるには:
もしtraversableの閉じようとしているかどうかがtrueであれば、終了します。
toUnloadをtraversableのアクティブなドキュメントの包含する子孫ナビゲーブルに設定します。
もしtoUnloadに対するアンロードがキャンセルされているかどうかの確認の結果がtrueであれば、終了します。
次のセッション履歴トラバーサルステップを追加するをtraversableに対して実行します:
afterAllUnloadsをアルゴリズムステップに設定し、それはtraversableを破棄するものです。
ドキュメントとその子孫をアンロードするをtraversableのアクティブなドキュメントを指定し、null、およびafterAllUnloadsを実行します。
ナビゲーブルには、ターゲット名を設定できます。これは、window.open()やa要素のtarget属性など、特定のAPIがそのナビゲーブルをターゲットにしてナビゲーションを行えるようにする文字列です。
有効なナビゲーブルターゲット名とは、ASCIIタブまたは改行の両方とU+003C (<)を含まない、かつU+005F (_)で始まらない文字列です。U+005F (_)で始まる名前は特別なキーワードのために予約されています。
有効なナビゲーブルターゲット名またはキーワードとは、有効なナビゲーブルターゲット名であるか、またはASCII大文字小文字を区別しない一致で次のいずれかの文字列です:_blank、_self、_parent、または_top。
これらの値は、ページがサンドボックス化されているかどうかによって異なる意味を持ちます。以下の(規範的でない)表にその概要が示されています。この表で「現在」とはリンクやスクリプトが存在するナビゲーブルを、「親」とはリンクやスクリプトが存在するナビゲーブルの親を、「トップ」とはリンクやスクリプトが存在するナビゲーブルのトップレベルのトラバース可能なナビゲーブルを、「新規」とは親がnullである新しいトラバース可能なナビゲーブルを指します(これにはさまざまなユーザー設定やユーザーエージェントのポリシーに基づいて、補助ブラウジングコンテキストが使用される場合があります)。「なし」とは何も起こらないことを、「おそらく新規」とは、「allow-popups」キーワードがsandbox属性で指定されている場合には「新規」と同じであり、そうでない場合は「なし」と同じであることを意味します。
| キーワード | 通常の効果 | 次のiframeでの効果...
|
|
|---|---|---|---|
sandbox="" |
sandbox="allow-top-navigation" |
||
| 指定なし(リンクおよびフォーム送信の場合) | 現在 | 現在 | 現在 |
| 空文字列 | 現在 | 現在 | 現在 |
_blank |
新規 | おそらく新規 | おそらく新規 |
_self |
現在 | 現在 | 現在 |
_parent(親がいない場合) |
現在 | 現在 | 現在 |
_parent(親がトップの場合) |
親/トップ | なし | 親/トップ |
_parent(親がトップでない場合) |
親 | なし | なし |
_top(トップが現在の場合) |
現在 | 現在 | 現在 |
_top(トップが現在でない場合) |
トップ | なし | トップ |
| 存在しない名前 | 新規 | おそらく新規 | おそらく新規 |
| 存在する名前で子孫の場合 | 指定された子孫 | 指定された子孫 | 指定された子孫 |
| 存在する名前で現在の場合 | 現在 | 現在 | 現在 |
| 存在する名前でトップが祖先の場合 | 指定された祖先 | なし | 指定された祖先/トップ |
| 存在する名前でトップが祖先でない場合 | 指定された祖先 | なし | なし |
| 共通のトップを持つその他の存在する名前 | 指定されたもの | なし | なし |
| 異なるトップを持ち、馴染みがあり、許可されたサンドボックス化されたナビゲータが1つの場合の名前 | 指定されたもの | 指定されたもの | 指定されたもの |
| 異なるトップを持ち、馴染みがあるが、許可されたサンドボックス化されたナビゲータが1つでない場合の名前 | 指定されたもの | なし | なし |
| 馴染みがない異なるトップを持つ名前 | 新規 | おそらく新規 | おそらく新規 |
サンドボックス化されたブラウジングコンテキストに対するほとんどの制限は、ナビゲーションアルゴリズムなど他のアルゴリズムによって適用されますが、以下に示すナビゲーブルを選択するためのルールでは適用されません。
ナビゲーブルを選択するためのルール、文字列name、ナビゲーブル currentNavigable、およびブール値noopenerが次のように与えられた場合:
chosenをnullに設定します。
windowTypeを"既存またはなし"に設定します。
sandboxingFlagSetをcurrentNavigableのアクティブなドキュメントのアクティブなサンドボックスフラグセットに設定します。
もしnameが空文字列であるか、またはASCIIケースインセンシティブで
"_self"と一致する場合、chosenを
currentNavigableに設定します。
それ以外の場合、nameがASCIIケースインセンシティブで
"_parent"と一致する場合、
chosenをcurrentNavigableの親に設定し、もし存在しない場合は
currentNavigableに設定します。
それ以外の場合、nameがASCIIケースインセンシティブで
"_top"と一致する場合、chosenをcurrentNavigableのトラバーサブルナビゲーブルに設定します。
それ以外の場合、nameがASCIIケースインセンシティブで
"_blank"と一致しない場合、
nameと同じターゲット名を持つナビゲーブルが存在し、
currentNavigableのアクティブなブラウジングコンテキストが
そのナビゲーブルのアクティブなブラウジングコンテキストと親しい場合、
そしてユーザーエージェントが両方のブラウジングコンテキストが十分に関連していると判断した場合は、
chosenをそのナビゲーブルに設定します。もし複数の一致するナビゲーブルが存在する場合は、
ユーザーエージェントが任意の一貫した方法、例えば最も最近開かれたもの、最も最近フォーカスされたもの、またはより密接に関連したものを選び、
chosenをそれに設定する必要があります。
これは問題#313でさらに正確に定義される予定です。
それ以外の場合、新しいトップレベルのトラバーサブルが要求されており、その後の動作はユーザーエージェントの設定および能力に依存します。これは次のリストから最初に該当するオプションに基づいてルールに従います。
ユーザーエージェントはポップアップがブロックされたことをユーザーに通知することができます。
ユーザーエージェントはポップアップがブロックされたことを開発者コンソールに報告することができます。
windowTypeを"新規および無制限"に設定します。
currentDocumentをcurrentNavigableのアクティブなドキュメントに設定します。
もしcurrentDocumentのクロスオリジンオープナーポリシーの値が"同一オリジン"
または"同一オリジンプラスCOEP"であり、
そしてcurrentDocumentのオリジンがcurrentDocumentの関連する設定オブジェクトのトップレベルオリジンと
同一オリジンでない場合:
noopenerをtrueに設定します。
nameを"_blank"に設定します。
windowTypeを"新規でオープナーなし"に設定します。
クロスオリジンオープナーポリシーが存在する場合、トップレベルのブラウジングコンテキストのアクティブなドキュメントとクロスオリジンのネストされたドキュメントは常にnoopenerをtrueに設定します。
chosenをnullに設定します。
targetNameを空文字列に設定します。
もしnameがASCIIケースインセンシティブで
"_blank"と一致しない場合は、targetNameをnameに設定します。
もしnoopenerがtrueである場合、chosenを新しいトップレベルのトラバーサブルを作成するの結果に、 null、targetName、およびcurrentNavigableを与えて設定します。
それ以外の場合:
chosenを新しいトップレベルのトラバーサブルを作成するの結果に、 currentNavigableのアクティブなブラウジングコンテキスト、 targetName、およびcurrentNavigableを与えて設定します。
もしsandboxingFlagSetのサンドボックス化されたナビゲーションブラウジングコンテキストフラグが設定されている場合は、 chosenのアクティブなブラウジングコンテキストの1つの許可されたサンドボックス化されたナビゲーターに、 currentNavigableのアクティブなブラウジングコンテキストを設定します。
もしsandboxingFlagSetのサンドボックスが補助ブラウジングコンテキストに伝播するフラグが設定されている場合、 sandboxingFlagSetで設定されているすべてのフラグがchosenのアクティブなブラウジングコンテキストのポップアップサンドボックスフラグセットに設定される必要があります。
新しく作成されたナビゲーブル
chosenがすぐにナビゲートされる場合、そのナビゲーションは"置き換え"ナビゲーションとして行われます。
chosenをcurrentNavigableに設定します。
何もしません。
ユーザーエージェントは常にcurrentNavigableを選択するようにユーザーがユーザーエージェントを設定できるようにすることを推奨します。
chosenとwindowTypeを返します。
ブラウジングコンテキストは、一連のドキュメントのプログラムによる表現であり、複数のドキュメントが単一のナビゲーブル内に存在することができます。各ブラウジングコンテキストには、対応するWindowProxyオブジェクトがあり、以下のものも含まれます:
オープナーブラウジングコンテキスト、ブラウジングコンテキストまたはnull、初期値はnull。
作成時のオープナーオリジン、オリジンまたはnull、初期値はnull。
ポップアップであるか、ブール値、初期値はfalse。
ポップアップであるかのこの仕様における唯一の必須影響は、関連するvisibleゲッターに対するものです。しかし、ユーザーエージェントはユーザーインターフェースの考慮事項にも使用することがあります。
補助的であるか、ブール値、初期値はfalse。
初期URL、URLまたはnull、初期値はnull。
仮想ブラウジングコンテキストグループID整数、初期値は0。これはクロスオリジンオープナーポリシーレポートで使用され、レポートオンリーポリシーが施行された場合に発生したであろうブラウジングコンテキストグループの切り替えを追跡するために使用されます。
ブラウジングコンテキストのアクティブウィンドウは、そのWindowProxyオブジェクトの[[Window]]内部スロットの値です。ブラウジングコンテキストのアクティブドキュメントは、そのアクティブウィンドウの関連するDocumentです。
ブラウジングコンテキストのトップレベルトラバーサブルは、そのアクティブドキュメントのノードナビゲーブルのトップレベルトラバーサブルです。
ブラウジングコンテキストの補助的であるかがtrueであるものは、補助的ブラウジングコンテキストとして知られています。補助的ブラウジングコンテキストは常にトップレベルのブラウジングコンテキストです。
別の補助的であるかという概念が必要かどうかは不明です。issue #5680では、オープナーブラウジングコンテキストがnullであるかどうかを使用することで、これを簡略化できる可能性があることが示されています。
現代の仕様では、ほとんどのケースでブラウジングコンテキストの概念を使用することを避けるべきです。代わりに、クロスオリジンオープナーポリシーによるブラウジングコンテキストグループの切り替えやエージェントクラスターの割り当ての微妙な点を扱っている場合を除いて、Documentやナビゲーブルの概念が通常はより適切です。
Documentのブラウジングコンテキストは、ブラウジングコンテキストまたはnullであり、初期値はnullです。
Documentは必ずしも非nullのブラウジングコンテキストを持つわけではありません。特に、データマイニングツールはブラウジングコンテキストをインスタンス化しないことが多いです。Documentが、createDocument()のようなAPIを使用して作成された場合、非nullのブラウジングコンテキストを持つことはありません。また、Documentは、かつてiframe要素のために作成され、その後ドキュメントから削除されたものであり、そのブラウジングコンテキストはnullになったため、関連するブラウジングコンテキストを持たない。
一般的には、WindowオブジェクトとDocumentオブジェクトの間には1対1の対応があります。ただし、Documentオブジェクトが非nullのブラウジングコンテキストを持つ限り、例外が1つあります。それは、同じブラウジングコンテキスト内で、最初のDocumentから次のDocumentにナビゲートされた場合、最初のabout:blankドキュメントから次のものに置き換えによって行われるときです。
nullまたはDocumentオブジェクトcreator、nullまたは要素embedder、およびブラウジングコンテキストグループ
groupが与えられた場合に、新しいブラウジングコンテキストとドキュメントを作成するには、次の手順を実行します:
browsingContextを新しいブラウジングコンテキストに設定します。
unsafeContextCreationTimeをunsafe shared current timeに設定します。
creatorOriginをnullに設定します。
creatorBaseURLをnullに設定します。
もしcreatorがnullでない場合:
creatorOriginをcreatorのオリジンに設定します。
creatorBaseURLをcreatorのドキュメントベースURLに設定します。
browsingContextの仮想ブラウジングコンテキストグループIDを creatorのブラウジングコンテキストのトップレベルブラウジングコンテキストの 仮想ブラウジングコンテキストグループIDに設定します。
sandboxFlagsを、browsingContextおよびembedderを与えて作成サンドボックスフラグを決定する結果に設定します。
originを、about:blank、sandboxFlags、およびcreatorOriginを与えてオリジンを決定する結果に設定します。
permissionsPolicyを、embedderおよびoriginを与えてパーミッションポリシーを作成する結果に設定します。[PERMISSIONSPOLICY]
agentを、origin、group、およびfalseを与えて類似オリジンウィンドウエージェントを取得する結果に設定します。
realm execution contextを、agentおよび以下のカスタマイズを与えて新しいJavaScriptレルムを作成する結果に設定します:
グローバルオブジェクトとして、新しいWindowオブジェクトを作成します。
グローバルthisバインディングとして、browsingContextのWindowProxyオブジェクトを使用します。
topLevelCreationURLを、embedderがnullであればabout:blankに、そうでなければembedderの関連する設定オブジェクトのトップレベル作成URLに設定します。
topLevelOriginを、embedderがnullであればoriginに、そうでなければembedderの関連する設定オブジェクトのトップレベルオリジンに設定します。
ウィンドウ環境設定オブジェクトを設定するをabout:blank、realm
execution context、null、topLevelCreationURL、およびtopLevelOriginを使用して実行します。
loadTimingInfoを新しいドキュメントロードタイミング情報に設定し、そのナビゲーション開始時間をunsafeContextCreationTimeおよび新しい環境設定オブジェクトのクロスオリジン隔離機能を使用して呼び出した時間の粗さ調整の結果に設定します。
documentを新しいDocumentに設定し、以下の属性を持たせます:
html"
text/html"
quirks"
about:blankである
もしcreatorがnullでない場合:
documentのリファラーをcreatorのシリアライゼーションに設定します。creatorのURLのシリアライゼーション。
もしcreatorのオリジンがcreatorの関連する設定オブジェクトのトップレベルオリジンと同一オリジンである場合、documentのクロスオリジンオープナーポリシーをcreatorのブラウジングコンテキストのトップレベルブラウジングコンテキストのアクティブドキュメントのクロスオリジンオープナーポリシーに設定します。
アサート: documentのURLおよびdocumentの関連する設定オブジェクトの作成URLがabout:blankであることを確認します。
documentをポストロードタスクの準備ができたとしてマークします。
html/head/bodyで埋めるをdocumentに与えて実行します。
documentをアクティブにするを実行します。
documentの読み込みを完全に終了するを実行します。
browsingContextとdocumentを返します。
新しいトップレベルのブラウジングコンテキストとドキュメントを作成するには、次の手順を実行します:
groupおよびdocumentを新しいブラウジングコンテキストグループとドキュメントを作成するの結果に設定します。
groupのブラウジングコンテキストセット[0]とdocumentを返します。
新しい補助的なブラウジングコンテキストとドキュメントを作成するには、次の手順を実行します:
openerTopLevelBrowsingContextをopenerのトップレベルトラバーサブルのアクティブブラウジングコンテキストに設定します。
groupをopenerTopLevelBrowsingContextのグループに設定します。
browsingContextおよびdocumentを、openerのアクティブドキュメント、null、およびgroupを与えて新しいブラウジングコンテキストとドキュメントを作成するの結果に設定します。
browsingContextの補助的であるをtrueに設定します。
browsingContextをgroupに追加するを実行します。
browsingContextのオープナーブラウジングコンテキストをopenerに設定します。
browsingContextの仮想ブラウジングコンテキストグループIDをopenerTopLevelBrowsingContextの仮想ブラウジングコンテキストグループIDに設定します。
browsingContextの作成時のオープナーオリジンをopenerのアクティブドキュメントのオリジンに設定します。
browsingContextとdocumentを返します。
オリジンを決定するには、次の手順を実行します:
もしsandboxFlagsがサンドボックス化されたオリジンブラウジングコンテキストフラグを設定している場合、新しい不透明オリジンを返します。
もしurlがnullであれば、新しい不透明オリジンを返します。
もしurlがabout:srcdocである場合:
アサート: sourceOriginはnullではありません。
sourceOriginを返します。
もしurlがabout:blankに一致する場合、sourceOriginがnullでなければsourceOriginを返します。
urlのオリジンを返します。
sourceOriginを返すケースでは、同じオリジンを持つ2つのDocumentが結果として得られ、document.domainが両方に影響を与えることになります。
ブラウジングコンテキストpotentialDescendantは、次のアルゴリズムがtrueを返す場合、ブラウジングコンテキストpotentialAncestorの先祖であると言われます:
potentialDescendantDocumentをpotentialDescendantのアクティブドキュメントに設定します。
もしpotentialDescendantDocumentが完全にアクティブでない場合、falseを返します。
ancestorBCsを、potentialDescendantDocumentの先祖ナビゲーブルの各メンバーのアクティブドキュメントのブラウジングコンテキストを取得することによって得られるリストに設定します。
もしancestorBCsが含むpotentialAncestorを含む場合、trueを返します。
falseを返します。
トップレベルブラウジングコンテキストとは、そのアクティブドキュメントのノードナビゲーブルがトラバーサブルナビゲーブルであるブラウジングコンテキストを指します。
それはトップレベルトラバーサブルである必要はありません。
ブラウジングコンテキストstartのトップレベルブラウジングコンテキストは、次のアルゴリズムの結果です:
もしstartのアクティブドキュメントが完全にアクティブでない場合、nullを返します。
navigableをstartのアクティブドキュメントのノードナビゲーブルに設定します。
navigableのアクティブブラウジングコンテキストを返します。
ブラウジングコンテキスト Aは、次のアルゴリズムがtrueを返す場合、2番目のブラウジングコンテキスト Bと親しいと言われます:
もしAのアクティブドキュメントのオリジンがBのアクティブドキュメントのオリジンと同一オリジンである場合、trueを返します。
もしAのトップレベルブラウジングコンテキストがBである場合、trueを返します。
もしBが補助的ブラウジングコンテキストであり、AがBのオープナーブラウジングコンテキストと親しい場合、trueを返します。
もしBの先祖ブラウジングコンテキストのいずれかが、Aのアクティブドキュメントと同じオリジンを持つ場合、trueを返します。
これは、AがBの先祖ブラウジングコンテキストである場合を含みます。
falseを返します。
トップレベルブラウジングコンテキストには、関連するグループ(nullまたはブラウジングコンテキストグループ)があります。これは最初はnullです。
ユーザーエージェントは、ブラウジングコンテキストグループセット(セットのブラウジングコンテキストグループを持ちます)。
ブラウジングコンテキストグループは、ブラウジングコンテキストセット(セットのトップレベルブラウジングコンテキストを保持します)。
トップレベルブラウジングコンテキストは、グループが作成されたときにそのグループに追加されます。その後に追加されるすべてのトップレベルブラウジングコンテキストは、補助的ブラウジングコンテキストとなります。
ブラウジングコンテキストグループには、関連するエージェントクラスターマップがあります(マップのエージェントクラスタキーからエージェントクラスタまで)。ユーザーエージェントは、何もアクセスできなくなったと判断されたときに、エージェントクラスタを収集する責任があります。
ブラウジングコンテキストグループには、関連する歴史的エージェントクラスタキーのマップがあり、これはマップのオリジンからエージェントクラスタキーまでです。このマップは、特定のオリジンに以前使用されたエージェントクラスタキーを記録することで、オリジンキー付きエージェントクラスタ機能の一貫性を確保するために使用されます。
歴史的エージェントクラスタキーのマップは、ブラウジングコンテキストグループの存続期間中にのみエントリを獲得します。
ブラウジングコンテキストグループには、クロスオリジン隔離モードがあり、これはクロスオリジン隔離モードです。これは最初は"none"です。
クロスオリジン隔離モードは、3つの可能な値のいずれかです: "none"、"logical"、または"concrete"。
"logical"および"concrete"は類似しています。これらは両方とも、以下の条件を満たすブラウジングコンテキストグループで使用されます:
すべてのトップレベルDocumentには"Cross-Origin-Opener-Policy: same-origin"が設定されています。
すべてのDocumentには、"Cross-Origin-Embedder-Policy"ヘッダーがあり、その値はクロスオリジン隔離に適合しています。
一部のプラットフォームでは、クロスオリジン隔離によって課されるさまざまな制限が適用されますが、クロスオリジン隔離機能を提供するために必要なセキュリティプロパティを提供するのが難しい場合があります。その結果、"concrete"のみがその機能にアクセスすることができます。"logical"は、この機能をサポートしていないプラットフォームで使用され、クロスオリジン隔離によって課されるさまざまな制限が適用されますが、機能は付与されません。
新しいブラウジングコンテキストグループとドキュメントを作成するには、次の手順を実行します:
groupを新しいブラウジングコンテキストグループに設定します。
追加してgroupをユーザーエージェントのブラウジングコンテキストグループセットに追加します。
browsingContextおよびdocumentを、null、null、およびgroupを指定して新しいブラウジングコンテキストとドキュメントを作成する結果に設定します。
追加してbrowsingContextをgroupに追加します。
groupとdocumentを返します。
追加してトップレベルブラウジングコンテキストbrowsingContextをブラウジングコンテキストグループgroupに追加します:
追加してbrowsingContextをgroupのブラウジングコンテキストセットに追加します。
browsingContextのグループをgroupに設定します。
削除してトップレベルブラウジングコンテキストbrowsingContextを削除します:
groupをbrowsingContextのグループに設定します。
browsingContextのグループをnullに設定します。
削除してbrowsingContextをgroupのブラウジングコンテキストセットから削除します。
もしgroupのブラウジングコンテキストセットが空であれば、削除してgroupをユーザーエージェントのブラウジングコンテキストグループセットから削除します。
追加と削除は、ブラウジングコンテキストグループの寿命を定義するための基本操作です。これらは、Documentおよびブラウジングコンテキストの高レベルの作成および破棄操作によって呼び出されます。
Documentオブジェクトがブラウジングコンテキストと等しい場合、そのブラウジングコンテキスト(すべてのDocumentが破棄された場合)であり、そのブラウジングコンテキストのWindowProxyがガベージコレクションの対象となっている場合、そのブラウジングコンテキストには二度とアクセスされることはありません。それがトップレベルブラウジングコンテキストである場合、この時点でユーザーエージェントはそれを削除する必要があります。
Document dが、dがアクティブドキュメントであり、かつnavigableがトップレベルトラバーサブルであるか、navigableのコンテナドキュメントが完全にアクティブである場合、完全にアクティブであると言います。
要素に関連付けられているため、子ナビゲーブルは常に特定のDocument、つまりそのコンテナドキュメントに結びついています。ユーザーエージェントは、子ナビゲーブルのコンテナドキュメントが完全にアクティブでない場合、ユーザーがそれと対話することを許可してはなりません。
次の例は、Documentがアクティブドキュメントであるが、完全にアクティブではない場合を示しています。ここでは、a.htmlがブラウザウィンドウに読み込まれ、b-1.htmlがiframeに読み込まれ、b-2.htmlとc.htmlが省略されています(それらは単に空のドキュメントでもかまいません)。
<!-- a.html -->
<!DOCTYPE html>
< html lang = "en" >
< title > Navigable A</ title >
< iframe src = "b-1.html" ></ iframe >
< button onclick = "frames[0].location.href = 'b-2.html'" > Click me</ button >
<!-- b-1.html -->
<!DOCTYPE html>
< html lang = "en" >
< title > Navigable B</ title >
< iframe src = "c.html" ></ iframe >
この時点で、a.html、b-1.html、およびc.htmlによって与えられるドキュメントはすべて、それぞれのアクティブドキュメントです。それらはすべて完全にアクティブです。
ボタンをクリックし、b-2.htmlから新しいDocumentをナビゲーブルBに読み込んだ後、次の結果が得られます:
a.htmlのDocumentは、ナビゲーブルAのアクティブドキュメントとして残り、かつ完全にアクティブです。
b-1.htmlのDocumentは、もはやナビゲーブルBのアクティブドキュメントではありません。したがって、それは完全にアクティブではありません。
新しいb-2.htmlのDocumentは、現在ナビゲーブルBのアクティブドキュメントであり、完全にアクティブでもあります。
c.htmlのDocumentは引き続きナビゲーブルCのアクティブドキュメントです。ただし、Cのコンテナドキュメントはb-1.htmlのDocumentであり、それ自体が完全にアクティブでないため、c.htmlのDocumentは現在完全にアクティブではありません。
ドラゴンの口へようこそ。ナビゲーション、セッション履歴、およびそのセッション履歴の移動は、この標準の中でも最も複雑な部分の一つです。
基本的な概念はそれほど難しくないかもしれません:
ユーザーはナビゲート可能なものを見ており、それがそのアクティブなドキュメントを表示しています。ユーザーはそれを別のURLにナビゲートします。
ブラウザはネットワークから指定されたURLを取得し、それを使用して新しいセッション履歴エントリを入力します。その際に新しく作成されたDocumentを使用します。
ブラウザはナビゲート可能なもののアクティブなセッション履歴エントリを新しく入力されたものに更新し、ユーザーに表示するアクティブなドキュメントを更新します。
その後、ユーザーはブラウザの戻るボタンを押して前のセッション履歴エントリに戻ります。
ブラウザはそのセッション履歴エントリに保存されているURLを確認し、それを使ってそのエントリのドキュメントを再取得して入力します。
ブラウザは再度ナビゲート可能なもののアクティブなセッション履歴エントリを更新します。
ここで見られるように、移動がナビゲーション(すなわち保存されたURLへのネットワークフェッチ)を引き起こす方法や、ナビゲーションがセッション履歴リストとインターフェースを必要とし、終了時にユーザーが適切なものを見ていることを確認する必要があることから、いくつかの複雑な絡み合いが表れています。しかし、実際の問題は、さまざまなエッジケースやWebプラットフォーム機能の相互作用によって発生します:
子ナビゲート可能なもの(例:iframeに含まれるもの)もナビゲートおよび移動できますが、これらのナビゲーションは単一のセッション履歴リストに統合する必要があります。ユーザーはブラウザタブ全体に対して単一の戻る/進むインターフェースしか持っていないからです。
ユーザーはセッション履歴を一度に1ステップ以上戻ることができるため(例:戻るボタンを長押しする)、子ナビゲート可能なものが関与している場合、同時に複数のナビゲート可能なものを移動することができます。これらすべてのナビゲート可能なものにわたって同期する必要があり、これには複数のイベントループやエージェントクラスタが関与する可能性があります。
ナビゲーション中に、サーバーは204または205ステータスコード、または`Content-Disposition: attachment`ヘッダーで応答することがあり、これによりナビゲーションが中断され、ナビゲート可能なものが元のアクティブなドキュメントに留まることになります。(これが移動により開始されたナビゲーション中に発生するとさらに悪化します!)
`Location`、`Refresh`、`X-Frame-Options`などの他のさまざまなHTTPヘッダーが、フェッチプロセス、またはDocument作成プロセス、またはその両方に寄与します。`Cross-Origin-Opener-Policy`ヘッダーはブラウジングコンテキストの選択と作成プロセスにも寄与します!
一部のナビゲーション(特にフラグメントナビゲーションやシングルページアプリのナビゲーション)は同期的であり、JavaScriptコードがナビゲーションの結果を即座に観察することを期待します。これにより、ツリー内の他のすべてのナビゲート可能なものがセッション履歴の表示を同期する必要があり、レースコンディションにさらされ、セッション履歴の競合するビューを解決する必要があります。
プラットフォームは、javascript:
URLs、srcdoc、iframe、およびbeforeunloadイベントなど、さまざまなナビゲーション関連の特別な機能を追加してきました。
以下では、これらの複雑さを適切にラベル付けされたセクションとアルゴリズムに区切り、可能な限り適切な導入文を提供することで、読者を案内することを試みました。それにもかかわらず、ナビゲーションとセッション履歴を真に理解したい場合は、通常のアドバイスが非常に役立つでしょう。
ステップ、非負の整数または "pending" で、初期値は "pending"。
URL、URL。
ドキュメント状態、ドキュメント状態。
クラシック履歴API状態、シリアライズされた状態で、初期値はStructuredSerializeForStorage(null)。
ナビゲーションAPI状態、シリアライズされた状態で、初期値はStructuredSerializeForStorage(undefined)。
ナビゲーションAPIキー、文字列で、初期値はランダムUUIDを生成する結果に設定されています。
ナビゲーションAPI ID、文字列で、初期値はランダムUUIDを生成する結果に設定されています。
スクロール復元モード、スクロール復元モードで、初期値は "auto"。
スクロール位置データ、ドキュメントの復元可能なスクロール領域のためのスクロール位置データです。
保存されたユーザー状態、実装依存であり、初期値はnullです。
例えば、いくつかのユーザーエージェントはフォームコントロールの値を保存したいかもしれません。
フォームコントロールの値を保存するユーザーエージェントは、方向性(要素のdir属性の値)も保存することが推奨されます。これにより、ユーザーが明示的にデフォルト以外の方向性で値を入力した場合、履歴の移動後に値が正しく表示されないことを防ぎます。
セッション履歴エントリのドキュメントを取得するには、そのドキュメント状態のドキュメントを返します。
シリアライズされた状態とは、StructuredSerializeForStorageによってシリアライズされたユーザーインターフェイス状態を表すオブジェクトです。時々、「状態オブジェクト」と非公式に呼ぶことがありますが、これは著者によって提供されたユーザーインターフェイス状態を表すオブジェクト、またはシリアライズされた状態をStructuredDeserializeによって逆シリアライズして作成されたオブジェクトです。
ページは追加されたシリアライズされた状態をセッション履歴に保存できます。これらは逆シリアライズされ、ユーザー(またはスクリプト)が履歴を戻ったときにスクリプトに返されます。これにより、著者はワンページアプリケーションでも「ナビゲーション」というメタファーを使用できるようになります。
シリアライズされた状態は、主に二つの目的で使用されます。まず、簡単な場合に作成者が解析を行わなくても済むように、状態の事前解析された説明をURLに保存するためです(ただし、ユーザーによって渡されるURLの処理には解析が必要なので、これはあくまで小さな最適化に過ぎません)。第二に、作成者がURLには保存しない状態を保存できるようにするためです。なぜなら、その状態は現在のドキュメントインスタンスにのみ適用され、新しいドキュメントが開かれた場合には再構築する必要があるからです。
後者の例としては、ポップアップがアニメーションを開始する正確な座標を追跡することが挙げられます。これにより、ユーザーが戻った場合、同じ場所にアニメーションさせることができます。または、URLに基づいてサーバーから取得されるデータのキャッシュへのポインタを保持するために使用される可能性があります。これにより、前後に移動する際に情報を再取得する必要がなくなります。
スクロール復元モードは、エージェントがエントリに移動するときに、保存されたスクロール位置(存在する場合)を復元するかどうかを示します。スクロール復元モードは次のいずれかです。
auto"
manual"
ドキュメント状態は、セッション履歴エントリ内に、Documentをどのように表示し、必要に応じて再作成するかに関する状態を保持します。これには次のものがあります。
ドキュメント、Documentまたはnullで、初期値はnullです。
履歴エントリがアクティブな場合、そのドキュメント状態にはDocumentがあります。しかし、Documentが完全にアクティブでない場合、リソースを解放するために破棄される可能性があります。そのような場合、このドキュメント項目はnullになります。その後、URLやその他のデータがセッション履歴エントリおよびドキュメント状態に保存され、ユーザーエージェントがエントリに移動する必要がある場合に、元の代わりに新しいDocumentが作成されます。
Documentが破棄されていない場合、履歴の移動中に再活性化される可能性があります。ブラウザがそのようなDocumentを保存するキャッシュは、前進後退キャッシュ、またはbfcache(あるいはおそらく"驚異的に高速な"キャッシュ)と呼ばれることがあります。
履歴ポリシーコンテナ、ポリシーコンテナまたはnullで、初期値はnullです。
リクエストリファラー、"no-referrer"、"client"、またはURLで、初期値は"client"です。
リクエストリファラーポリシー、リファラーポリシーで、初期値はデフォルトのリファラーポリシーです。
リクエストリファラーポリシーは、履歴ポリシーコンテナのリファラーポリシーとは異なります。前者はこのドキュメントのフェッチに使用され、後者はこのドキュメントによるフェッチを制御します。
発信者のオリジン、オリジンまたはnullで、初期値はnullです。
オリジン、オリジンまたはnullで、初期値はnullです。
これは、"about:"スキームのDocumentのオリジンに設定するオリジンです。これをここに保存するのは、これらのDocumentが移動中に復元される際にも使用されるからです。それらはネットワークにアクセスせずにローカルで再構築されるためです。また、セッション履歴エントリが再入力された前後のオリジンを比較するためにも使用されます。オリジンが変更された場合、ナビゲーブルターゲット名がクリアされます。
aboutベースURL、URLまたはnullで、初期値はnullです。
これは、"about:"スキームのDocumentに対してのみ設定され、これらのDocumentのフォールバックベースURLになります。これは、発信者のDocumentのドキュメントベースURLのスナップショットです。
リソース、文字列、POSTリソースまたはnullで、初期値はnullです。
文字列はHTMLとして扱われます。これは、iframeのsrcdocドキュメントのソースを保存するために使用されます。
リロード保留中ブール値、初期値はfalseです。
これまでに入力されたことがあるブール値、初期値はfalseです。
ナビゲーブルターゲット名文字列、初期値は空の文字列です。
復元されなかった理由、復元されなかった理由またはnullで、初期値はnullです。
ユーザーエージェントは、ドキュメント状態のドキュメントがnullでない場合、ドキュメントおよびその子孫を破棄することができますが、そのドキュメントが完全にアクティブではない場合に限ります。
この制約を除いて、本標準では、ユーザーエージェントがドキュメント状態に保存されているドキュメントを破棄するタイミングと、それをキャッシュとして保持するタイミングについては指定していません。
POSTリソースには以下のものがあります。
リクエストボディ、バイトシーケンスまたはエラー。
これは並列でのみアクセスされるため、メモリに保持する必要はありません。ただし、毎回同じバイトシーケンスを返す必要があります。これがリソースのディスク上での変更やアクセス不能のために不可能な場合、これはエラーに設定されなければなりません。
リクエストコンテンツタイプ、`application/x-www-form-urlencoded`、`multipart/form-data`、または`text/plain`。
ネストされた履歴には以下のものがあります。
識別子、一意の内部値。
エントリ、リスト形式のセッション履歴エントリ。
これは後で、子ナビゲーブルをリロードの間に識別する方法を含むことになります。
セッション履歴のいくつかの連続するエントリは、同じドキュメント状態を共有することがあります。これは、通常のナビゲーションを経て最初のエントリに到達し、次のエントリがhistory.pushState()によって追加された場合に発生することがあります。また、フラグメントへのナビゲーションによっても発生することがあります。
同じドキュメント状態を共有するすべてのエントリ(したがって、単に特定のドキュメントの異なる状態にすぎないエントリ)は、構造上連続しています。
Documentには、最新エントリがあり、それはセッション履歴エントリまたはnullです。
これは、特定のDocumentによって最後に表現されたエントリです。単一のDocumentは、時間の経過とともに多くのセッション履歴エントリを表すことができ、多くの連続するセッション履歴エントリが上記で説明したように同じドキュメント状態を共有することがあります。
単一の信頼できる情報源を維持するために、トラバース可能なナビゲーブルのセッション履歴エントリに対するすべての変更は同期する必要があります。これは、セッション履歴がすべての子孫ナビゲーブルおよび複数のイベントループによって影響を受ける方法のために特に重要です。これを達成するために、セッション履歴トラバース並列キュー構造を使用します。
セッション履歴トラバース並列キューは、並列キューに非常に似ています。これは、順序付きセットであるアルゴリズムセットを持ちます。
項目は、セッション履歴トラバース並列キューのアルゴリズムセット内にあり、アルゴリズムステップまたは同期ナビゲーションステップのどちらかです。これらは、特定のナビゲーブルに関わるアルゴリズムステップです。
セッション履歴トラバースステップを追加するには、トラバース可能なナビゲーブルに対して、アルゴリズムステップstepsを与え、appendでstepsをtraversableのセッション履歴トラバースキューのアルゴリズムセットに追加します。
セッション履歴同期ナビゲーションステップを追加するには、ナビゲーブルtargetNavigableに関わるアルゴリズムステップstepsを与え、appendでstepsをsynchronous navigation stepsとしてtargetNavigableをターゲットとするtraversableのセッション履歴トラバースキューのアルゴリズムセットに追加します。
新しいセッション履歴トラバース並列キューを開始するには:
sessionHistoryTraversalQueueを新しいセッション履歴トラバース並列キューに設定します。
次のステップを並列で実行します:
sessionHistoryTraversalQueueを返します。
このセクションでは、セッション履歴を操作する際に標準全体で実行するさまざまな操作をまとめています。これらの操作が何をするかを理解する最良の方法は、それらが呼び出される箇所を確認することです。
ナビゲーブルのセッション履歴エントリを取得するには:
navigableのトラバース可能なナビゲーブルをtraversableに設定します。
アサート: これがtraversableのセッション履歴トラバースキュー内で実行されていることを確認します。
もしnavigableがtraversableであるなら、traversableのセッション履歴エントリを返します。
traversableのセッション履歴エントリの各entryについて、entryのドキュメント状態をdocStatesに追加します。
各docStateについて、docStatesの中で次の操作を行います:
アサート: このステップには到達しないことを確認します。
整数targetStepを与えて、ナビゲーブルのナビゲーションAPIのためのセッション履歴エントリを取得するには:
rawEntriesをセッション履歴エントリを取得した結果に設定します。
entriesForNavigationAPIを新しい空のリストに設定します。
startingIndexを、rawEntriesの中で、targetStep以下の最大のステップを持つセッション履歴エントリのインデックスに設定します。
なぜそれがtargetStep以下の最大のステップであるかを理解するために、この例を参照してください。
rawEntries[startingIndex]をentriesForNavigationAPIに追加します。
startingOriginをrawEntries[startingIndex]のドキュメント状態のオリジンに設定します。
iをstartingIndex − 1に設定します。
iが0より大きい間、次の操作を行います:
iをstartingIndex + 1に設定します。
iがrawEntriesのサイズより小さい間、次の操作を行います:
entriesForNavigationAPIを返します。
トラバース可能なナビゲーブルのフォワードセッション履歴をクリアするには:
アサート: これがnavigableのセッション履歴トラバースキュー内で実行されていることを確認します。
stepをnavigableの現在のセッション履歴ステップに設定します。
entryListsをnavigableのセッション履歴エントリからなる順序付きセットに設定します。
各entryListについて、entryListsの中で次の操作を行います:
トラバース可能なナビゲーブルの一部であるすべての使用済み履歴ステップを取得するには:
アサート: これがtraversableのセッション履歴トラバースキュー内で実行されていることを確認します。
stepsを非負の整数の空の順序付きセットに設定します。
entryListsをtraversableのセッション履歴エントリからなる順序付きセットに設定します。
各entryListについて、entryListsの中で次の操作を行います:
stepsを返し、昇順にソートします。
特定のアクションによって、ナビゲーブルが新しいリソースにナビゲートされることがあります。
例えば、ハイパーリンクのフォロー、フォーム送信、およびwindow.open()やlocation.assign()メソッドは、すべてナビゲーションを引き起こす可能性があります。
ナビゲートアルゴリズム自体に入る前に、それが使用するいくつかの重要な構造を確立する必要があります。
ソーススナップショットパラメータ 構造体は、ナビゲーションを開始するDocumentからデータをキャプチャするために使用されます。これは、ナビゲーションの開始時にスナップショットされ、ナビゲーションのライフタイム全体で使用されます。次の項目があります:
ドキュメントであるsourceDocumentを指定して、ソーススナップショットパラメーターをスナップショットするために、次の要素を持つ新しいソーススナップショットパラメーターを返します。
ターゲットスナップショットパラメータ 構造体は、ナビゲートされるナビゲーブルからデータをキャプチャするために使用されます。ソーススナップショットパラメータと同様に、ナビゲーションの開始時にスナップショットされ、ナビゲーションのライフタイム全体で使用されます。次の項目があります:
targetNavigableとしてナビゲーブルを与えたときにターゲットスナップショットパラメータをスナップショットするには、次のようにして返します:サンドボックスフラグを、targetNavigableのアクティブブラウジングコンテキストおよびtargetNavigableのコンテナを与えた場合のサンドボックスフラグの決定の結果として設定します。
ナビゲーションプロセスの多くは、新しいドキュメントをどのように作成するかを決定することに関係しており、最終的にはDocumentオブジェクトを作成および初期化するアルゴリズムで行われます。そのアルゴリズムへのパラメーターは、次の項目を持つナビゲーションパラメーター 構造体を通じて追跡されます:
Documentが作成された後に受け取るアルゴリズム
Document用に予約された環境
Documentに使用するオリジン
Documentに使用するポリシーコンテナ
Documentに課すサンドボックスフラグセット
Documentに使用するクロスオリジンオープナーポリシー
Documentのためにナビゲーションタイミングエントリを作成するために使用されるNavigationTimingType
DocumentのaboutベースURLを設定するために使用されるURLまたはnull
一度ナビゲーションパラメータ構造体が作成されると、この標準はその項目を変更しません。これらは他のアルゴリズムに渡されるだけです。
ナビゲーションIDは、ナビゲーション中に生成されるUUID文字列です。これは、WebDriver BiDi仕様とのインターフェースや進行中のナビゲーションを追跡するために使用されます。[WEBDRIVERBIDI]
Document作成後、関連するトラバーサブルナビゲーブルのセッション履歴が更新されます。NavigationHistoryBehavior列挙型は、ナビゲートアルゴリズムにセッション履歴の更新タイプを指定するために使用されます。それは次のいずれかです:
push"
replace"
auto"
push"または"replace"に変換されます。通常は"push"になりますが、特定の状況では"replace"になることがあります。
履歴処理の挙動は、"push"または"replace"であり、初期の"auto"値から解決されたものです。
urlがDocumentのdocumentである場合に、ナビゲーションは必ず置き換えになります:
urlのスキームが"javascript"である場合
documentの初期about:blankであるかどうかがtrueである場合
プラットフォームのさまざまな部分では、ユーザーがナビゲーションに関与しているかどうかを追跡します。ユーザーのナビゲーション関与は、次のいずれかです:
ブラウザUI"
アクティベーション"
なし"
特定の呼び出しサイトでの便宜のために、eventがイベントである場合のユーザーのナビゲーション関与は次のように定義されます:
確認:このアルゴリズムはアクティベーション動作の定義の一部として呼び出されています。
"なし"を返します。
ナビゲートするには、ナビゲーブル
navigable を
URL
url へ、ドキュメント ソースドキュメント を使用してナビゲートします。オプションで POSTリソース、
文字列、またはnullの documentResource(デフォルトはnull)、オプションのレスポンスまたはnull response(デフォルトはnull)、オプションのブール値
exceptionsEnabled(デフォルトはfalse)、オプションのナビゲーション履歴の処理方法
historyHandling
(デフォルトは"自動")、オプションのシリアライズされた状態またはnullの navigationAPIState(デフォルトはnull)、オプションのエントリリストまたはnullのformDataEntryList(デフォルトはnull)、オプションのリファラーポリシー referrerPolicy(デフォルトは空文字列)、オプションのユーザーのナビゲーション関与
userInvolvement(デフォルトは"none"):
cspNavigationType を "form-submission" とし、formDataEntryList
がnullでない場合、それ以外は "other" とします。
sourceSnapshotParams を、sourceDocumentを基にしたスナップショットを作成する結果とします。
initiatorOriginSnapshot を、sourceDocumentのオリジンとします。
initiatorBaseURLSnapshot を、sourceDocumentのドキュメント基本URLとします。
もしsourceDocumentのノードナビゲーブルが、sourceSnapshotParamsを考慮した上でnavigableのサンドボックスによるナビゲートの許可を受けていない場合、以下を実行します。
もしexceptionsEnabled が true であれば、"SecurityError" DOMException
をスローします。
リターンします。
navigationId を、ランダムUUID生成の結果とします。 [WEBCRYPTO]
もし周辺エージェントがnavigableのアクティブドキュメントの関連エージェントと等しい場合は、これらの手順を続行します。そうでない場合は、navigableのアクティブウィンドウに基づいてグローバルタスクをキューに追加し、これらの手順を続行します。
これは、navigableのアクティブドキュメントの多くのプロパティを調べようとしているためです。これらのプロパティは理論的には適切なイベントループでのみアクセス可能です。(ただし、同じイベントループ内でフラグメントナビゲーションが同期的に有効になる必要があるため、タスクを無条件にキューに追加することは望ましくありません。)
もう一つの実装戦略としては、関連情報をイベントループ間で複製するか、または正規の「ブラウザプロセス」に複製して、タスクをキューに追加せずに参照できるようにする方法があります。この方法は、エッジケースでは、ターゲットイベントループで関連プロパティが変更されましたが、まだ複製されていない場合、ここで指定するものとは異なる結果を生む可能性があります。どの戦略がブラウザの動作に最も適しているかを確認するために、さらなるテストが必要です。
もしnavigableのアクティブドキュメントのアンロードカウンターが0より大きい場合、WebDriver BiDiナビゲーション失敗を、WebDriver BiDiナビゲーションステータス(idがnavigationId、ステータスが
"キャンセル"、urlがurl)を使って呼び出し、リターンします。
containerをnavigableのコンテナとします。
もしcontainerがiframeエレメントであり、containerが遅延読み込み要素のステップを実行するとtrueを返す場合、遅延読み込み要素の交差観測を停止し、containerの遅延読み込み再開ステップをnullに設定します。
もしナビゲーションが置換でなければならない場合、urlとnavigableのアクティブドキュメントに基づいて、historyHandlingを"置換"に設定します。
もしnavigableの親がnullでない場合、navigableのロードイベントの遅延モードをtrueに設定します。
targetBrowsingContextをnavigableのアクティブブラウジングコンテキストとします。
targetSnapshotParamsを、navigableに基づいてターゲットスナップショットの作成の結果とします。
WebDriver
BiDiナビゲーション開始を、targetBrowsingContextと新しいWebDriver BiDiナビゲーションステータス(idがnavigationId、ステータスが"保留"、urlがurl)を使って呼び出します。
もしnavigableの進行中のナビゲーションが"traversal"である場合、以下の手順を実行します:
WebDriver
BiDiナビゲーション失敗を、targetBrowsingContextと新しいWebDriver BiDiナビゲーションステータス(idがnavigationId、ステータスが"キャンセル"、urlがurl)を使って呼び出します。
リターンします。
現在ナビゲーブルが履歴のトラバースステップを適用している場合、ナビゲートの試みは無視されます。
進行中のナビゲーションをnavigableのnavigationIdに設定します。
これにより、navigableの他の進行中のナビゲーションが中止されます。ナビゲーションのある時点で、進行中のナビゲーションの変更がさらなる作業の放棄を引き起こすからです。
もしurlのスキームが"javascript"である場合、次の手順を実行します:
グローバルタスクをキューに追加し、navigableのアクティブウィンドウに基づいてjavascript:
URLをナビゲートします。navigable、url、historyHandling、initiatorOriginSnapshot、およびcspNavigationTypeを指定します。
リターンします。
次のすべてがtrueの場合:
userInvolvementが"ブラウザUI"ではない;
navigableのアクティブドキュメントのオリジンが、sourceDocumentのオリジンと同一オリジンドメインである;
navigableのアクティブドキュメントの初期about:blankがfalseである;
その場合:
navigationをnavigableのアクティブウィンドウのナビゲーションAPIとします。
もしdocumentResourceがPOSTリソースである場合、entryListForFiringをformDataEntryListとし、そうでない場合はnullとします。
もしnavigationAPIStateがnullでない場合、navigationAPIStateForFiringをnavigationAPIStateとし、そうでない場合はストレージ用に構造化シリアライズ(未定義)とします。
プッシュ/置換/リロードナビゲートイベントを発火する結果をnavigationに対して実行します。navigationTypeをhistoryHandlingに設定し、isSameDocumentをfalseに設定し、userInvolvementをuserInvolvementに設定し、formDataEntryListをentryListForFiringに設定し、destinationURLをurlに設定し、navigationAPIStateをnavigationAPIStateForFiringに設定します。
もしcontinueがfalseの場合、リターンします。
ユーザーの関与が"ブラウザUI"であるナビゲーションや、クロスオリジンドメインのsourceDocumentによって開始されたナビゲーションでも、以前のフラグメントにナビゲートパスを通過する場合、ナビゲートイベントが発火される可能性があります。
並行して、次の手順を実行します:
unloadPromptCanceledをアンロードがキャンセルされるかどうかを確認する結果とし、navigableのアクティブドキュメントの包括的子孫ナビゲーブルに対して実行します。
もしunloadPromptCanceledがtrueである場合、またはnavigableの進行中のナビゲーションがもはやnavigationIdでない場合、以下を実行します:
WebDriver
BiDiナビゲーション失敗をtargetBrowsingContextと新しいWebDriver BiDiナビゲーションステータス(idがnavigationId、ステータスが"キャンセル"、urlがurl)を使って呼び出します。
これらの手順を中止します。
グローバルタスクをキューに追加し、navigableのアクティブウィンドウに基づいてドキュメントとその子孫を中止します。
もしurlがabout:blankに一致するか、about:srcdocである場合、次の手順を実行します:
documentStateのオリジンをinitiatorOriginSnapshotに設定します。
documentStateのabout基本URLをinitiatorBaseURLSnapshotに設定します。
historyEntryを新しいセッション履歴エントリとし、そのURLをurlに、she-document-stateをdocumentStateに設定します。
navigationParamsをnullとします。
もしresponseがnullでない場合:
policyContainerをナビゲーションパラメータポリシーコンテナを決定する結果とし、responseのURL、null、sourceDocumentのポリシーコンテナのクローン、navigableのコンテナドキュメントのポリシーコンテナのクローン、およびnullを与えて実行します。
finalSandboxFlagsをtargetSnapshotParamsのサンドボックスフラグとpolicyContainerのCSPリストのCSP由来のサンドボックスフラグのunionとします。
responseOriginをオリジンの決定の結果とし、responseのURL、finalSandboxFlags、およびdocumentStateの発起者オリジンを与えて実行します。
coopを新しいクロスオリジンオープナーポリシーとします。
coopEnforcementResultを新しいクロスオリジンオープナーポリシーの執行結果とし、次の設定を行います
navigationParamsを新しいナビゲーションパラメータとし、次の設定を行います
ナビゲート"
履歴エントリのドキュメントを入力しようとする
historyEntry に対して、navigable、"ナビゲート"、sourceSnapshotParams、targetSnapshotParams、navigationId、navigationParams、cspNavigationType
を使用し、allowPOST を true に設定し、完了ステップ を次のステップに設定します:
セッション履歴トラバースステップを navigableのトラバーサブルに追加し、クロスドキュメントナビゲーションを完了し、navigable、historyHandling、historyEntryを基に行います。
通常のクロスドキュメントナビゲーションの場合、まずセッション履歴エントリの作成に進み、
Documentを使用しますが、途中で中止されなかったナビゲーションは、最終的に以下のいずれかのアルゴリズムを呼び出すことになります。
クロスドキュメントナビゲーションを完了するために、 navigable navigable、 履歴処理の挙動 historyHandling、 セッション履歴エントリ historyEntry を指定します:
アサートします: これはnavigableのトラバース可能なnavigableの セッション履歴トラバーサルキューで実行されています。
navigableのロードイベントの遅延をfalseに設定します。
もしhistoryEntryのドキュメントがnullである場合、リターンします。
これは履歴エントリのドキュメントを入力しようとする試みが、ナビゲーションのキャンセルや204 No Contentレスポンスなどの結果としてドキュメントを作成しなかったことを意味します。
次のすべてがtrueである場合:
navigableの親がnullである。
historyEntryのドキュメントの ブラウジングコンテキストが、 非nullのオープナーのブラウジングコンテキストを持つ 補助ブラウジングコンテキストではない。
historyEntryのドキュメントの オリジンが、 navigableのアクティブドキュメントの オリジンと異なる。
その場合、historyEntryのドキュメント状態の navigableターゲット名を空文字列に設定します。
もしhistoryHandlingが"replace"である場合、
navigableのアクティブなセッション履歴エントリをentryToReplaceとします。
そうでない場合はnullに設定します。
navigableのトラバース可能なnavigableをtraversableとします。
targetStepをnullに設定します。
セッション履歴エントリの取得の結果を navigableのためにtargetEntriesとします。
もしentryToReplaceがnullである場合、次を実行します:
順方向のセッション履歴をクリアし、 traversableのものとします。
traversableの現在のセッション履歴ステップ + 1を targetStepに設定します。
historyEntryのステップをtargetStepに設定します。
追加します。 historyEntryをtargetEntriesに追加します。
そうでない場合:
置換します。 entryToReplaceをhistoryEntryにtargetEntries内で置き換えます。
もしhistoryEntryのドキュメント状態の オリジンが entryToReplaceのドキュメント状態の オリジンと 同一オリジンである場合、 historyEntryのナビゲーションAPIキーを entryToReplaceのナビゲーションAPIキーに設定します。
traversableの現在のセッション履歴ステップを targetStepに設定します。
プッシュ/リプレース履歴ステップを適用します。 targetStepをtraversableに対して適用し、historyHandlingに基づいて実行します。
javascript:
URLの特別なケースjavascript:
URLには、仕様に関するさまざまな問題を記録した専用のラベルがあります。
javascript: URLにナビゲートするには、navigable targetNavigable、
URL url、
履歴処理の挙動
historyHandling、
origin
initiatorOrigin、
および文字列cspNavigationTypeを指定します。
現在のナビゲーションを設定し、targetNavigableをnullにします。
もしinitiatorOriginが、targetNavigableのアクティブドキュメントのoriginと同一オリジンドメインでない場合、リターンします。
requestを新しいrequestとして設定し、そのURLをurlに設定します。
これは次のステップに進むための合成されたリクエストであり、ネットワークには到達しません。
もし、コンテンツセキュリティポリシーによってナビゲーションリクエストをブロックすべきかをrequestとcspNavigationTypeを与えて実行した結果が"Blocked"である場合、リターンします。[CSP]
newDocumentをjavascript:
URLを評価して、targetNavigable、url、およびinitiatorOriginを指定して取得します。
もしnewDocumentがnullである場合、リターンします。
この場合、JavaScriptコードは実行されましたが、新しいDocumentは作成されていないため、ナビゲーションは実行されません。
entryToReplaceをtargetNavigableのアクティブなセッション履歴エントリとして設定します。
oldDocStateをentryToReplaceのドキュメント状態として設定します。
documentStateを新しいドキュメント状態として以下のプロパティを設定します:
historyEntryを新しいセッション履歴エントリとして以下のプロパティを設定します:
このURLでは、実際にナビゲーションアルゴリズムに渡されたjavascript:
URLは使用されません。これにより、javascript:
URLがセッション履歴に保存されることはなく、そのためセッション履歴に遡ることはできません。
セッション履歴トラバーサルステップを追加し、targetNavigableのトラバーサブルに、クロスドキュメントナビゲーションの完了と共にtargetNavigable、historyHandling、およびhistoryEntryを指定して実行します。
javascript: URLを評価するには、navigable targetNavigable、
URL url、
およびorigin
newDocumentOriginを指定します。
urlStringをURLシリアライザをurlに対して実行した結果とします。
encodedScriptSourceをurlStringから先頭の"javascript:"を取り除いた結果とします。
scriptSourceをUTF-8デコードを行い、 パーセントデコードされたencodedScriptSourceを設定します。
settingsをtargetNavigableのアクティブドキュメントの関連設定オブジェクトに設定します。
baseURLをsettingsのAPIベースURLに設定します。
scriptをクラシックスクリプトを作成し、scriptSource、settings、baseURLを指定し、デフォルトクラシックスクリプトフェッチオプションで設定します。
evaluationStatusをクラシックスクリプトを実行した結果とします。
resultをnullに設定します。
もしevaluationStatusが正常終了であり、evaluationStatus.[[Value]]が文字列である場合、resultにevaluationStatus.[[Value]]を設定します。
それ以外の場合はnullをリターンします。
responseを新しいレスポンスとして以下のプロパティを設定します:
Content-Type`,
`text/html;charset=utf-8`) »
UTF-8へのエンコードにより、サロゲートペアが失われる可能性があります。
policyContainerをtargetNavigableのアクティブドキュメントのポリシーコンテナに設定します。
finalSandboxFlagsをpolicyContainerのCSPリストのCSP派生のサンドボックスフラグに設定します。
coopをtargetNavigableのアクティブドキュメントのクロスオリジンオープナーポリシーに設定します。
coopEnforcementResultを新しいクロスオリジンオープナーポリシー実施結果として以下のプロパティを設定します:
navigationParamsを新しいナビゲーションパラメータとして以下のプロパティを設定します:
Documentの参照元がnullになります。これは正しいですか?
navigate"
HTMLドキュメントを読み込む結果をnavigationParamsに従って返します。
フラグメントへナビゲートするために、ナビゲーブル navigable、URL url、履歴処理の挙動 historyHandling、ユーザーのナビゲーション関与 userInvolvement、 シリアライズされた状態またはnull navigationAPIState、およびナビゲーションID navigationIdが与えられたとき:
navigationをnavigableのアクティブウィンドウのナビゲーションAPI とします。
destinationNavigationAPIStateをnavigableのアクティブセッション履歴エントリのナビゲーションAPI状態 とします。
もしnavigationAPIStateがnullでない場合は、destinationNavigationAPIState にnavigationAPIStateを設定します。
continueを、navigationでnavigateイベントを発生させる結果とします。navigationTypeをhistoryHandling
に設定し、isSameDocumentをtrueに設定し、userInvolvementをuserInvolvementに設定し、
destinationURL
をurlに設定し、navigationAPIStateをdestinationNavigationAPIStateに設定します。
もしcontinueがfalseの場合は、終了します。
historyEntryを新しいセッション履歴エントリとして、以下を持つものとします:
navigation.navigate()を使用したナビゲーションでは、新しいナビゲーションAPI状態に、stateオプションで提供された値が使用されます。(このオプションに値が提供されていない場合は未定義のシリアライズに設定されます。)他のフラグメントナビゲーション、特にユーザーが発生させたものでは、ナビゲーションAPI状態は前のエントリから引き継がれます。
クラシック履歴API状態は決して引き継がれません。
entryToReplaceを、navigableのアクティブセッション履歴エントリとし、
もしhistoryHandlingが"置換"の場合はnullとします。
historyを、navigableのアクティブドキュメントの履歴オブジェクト とします。
scriptHistoryIndexをhistoryのインデックスとします。
scriptHistoryLengthをhistoryの長さとします。
もしhistoryHandlingが"プッシュ"の場合は:
historyの状態をnullに設定します。
scriptHistoryIndexをインクリメントします。
scriptHistoryLengthをscriptHistoryIndex + 1に設定します。
navigableのアクティブドキュメントのURLをurlに設定します。
navigableのアクティブセッション履歴エントリをhistoryEntry に設定します。
履歴ステップ適用のためのドキュメントを更新を、navigableのアクティブドキュメント、 historyEntry、true、scriptHistoryIndex、scriptHistoryLength、およびhistoryHandling を与えて実行します。
このアルゴリズムは、単一のフラグメントナビゲーションの結果として2回呼び出されます。1回目は同期的に呼び出され、scriptHistoryIndexとscriptHistoryLengthの推測値が設定され、history.stateがnullに設定され、さまざまなイベントが発生します。2回目は非同期的に呼び出され、インデックスと長さの最終値が設定され、history.stateは変更されず、イベントも発生しません。
navigableのアクティブドキュメントを与えて、フラグメントにスクロールします。
スクロールが失敗する場合、それはドキュメントが新しいものであり、関連するIDがまだパースされていないためです。その場合、履歴ステップ適用のためのドキュメントを更新の2回目の非同期呼び出しがスクロール処理を行います。
navigableのトラバース可能なナビゲーブル をtraversableとします。
navigableを含むセッション履歴同期ナビゲーションステップを追加 をtraversableに追加します。
traversable、navigable、historyEntry、entryToReplace、およびhistoryHandlingを与えて、同一ドキュメント内ナビゲーションを完了します。
navigableのアクティブブラウジングコンテキストと、新しいWebDriver BiDiナビゲーションステータスを含む、WebDriver
BiDiフラグメントナビゲーションを呼び出します。そのIDはnavigationId、URLはurl、ステータスは"complete"です。
同一ドキュメント内ナビゲーションを完了するために、トラバース可能なナビゲーブル traversable、ナビゲーブル targetNavigable、セッション履歴エントリ targetEntry、セッション履歴エントリまたはnullentryToReplace、および履歴処理の挙動 historyHandlingが与えられたとき:
これは、フラグメントナビゲーションおよびURLおよび履歴更新ステップによって使用されます。これらはセッション履歴の唯一の同期的な更新です。同期的であることから、これらのアルゴリズムはトップレベルのトラバース可能なナビゲーブルのセッション履歴トラバースキューの外部で実行されます。これにより、トップレベルのトラバース可能なナビゲーブルの現在のセッション履歴ステップと同期が取れなくなります。このアルゴリズムは、競合状態による競合を解決するために使用されます。
アサート: これはtraversableのセッション履歴トラバースキューで実行されています。
もしtargetNavigableのアクティブセッション履歴エントリがtargetEntryでない場合は、終了します。
targetStepをnullに設定します。
targetEntriesをtargetNavigableのためにセッション履歴エントリを取得する結果とします。
もしentryToReplaceがnullの場合は:
traversableのフォワードセッション履歴をクリア します。
targetStepをtraversableの現在のセッション履歴ステップ + 1に設定します。
targetEntryのステップをtargetStepに設定します。
targetEntryをtargetEntriesに追加 します。
それ以外の場合:
entryToReplaceをtargetEntriesの中でtargetEntryと置換します。
targetStepをtraversableの現在のセッション履歴ステップに設定します。
プッシュ/置換履歴ステップを適用 し、historyHandlingが与えられたtargetStepをtraversableに適用します。
これは、"置換"ナビゲーションでも行われます。これは複数の同期ナビゲーション間の競合状態を解決します。
非フェッチスキームドキュメントを作成しようとする 入力は非フェッチスキームナビゲーションパラメータであり、構造体です。これは、非フェッチスキームナビゲーションケースに関連するパラメータのみを保持する軽量バージョンです。次の項目を持ちます:
外部ソフトウェアパッケージの起動を確認するためのユーザー向けプロンプトで使用される可能性のあるオリジン
これは、ドキュメントの状態のイニシエーターのオリジンとは少し異なり、非フェッチスキームナビゲーションパラメータのイニシエーターのオリジンは、リダイレクトチェーンで最後に非フェッチスキームURLにリダイレクトされるまでリダイレクトを追跡します。
NavigationTimingType、新しいDocumentのナビゲーションタイミングエントリを作成するために使用されます
もしurlがnavigableに影響を与えないメカニズムで処理されるべき場合、例としてurlのスキームが外部で処理される場合は:
url、navigable、navigationParamsのターゲットスナップショットサンドボックスフラグ、 navigationParamsのソーススナップショットに一時的なアクティベーションがある、 navigationParamsのイニシエーターのオリジン を指定して、外部ソフトウェアに引き渡します。
nullを返します。
urlを処理し、例えば指定されたスキームがサポートされているプロトコルの1つではないためにエラーメッセージをインラインで表示するか、または指定されたスキームの登録されたハンドラーを選択するためのインラインプロンプトを表示します。インラインコンテンツを表示する結果を返します。navigable、 navigationParamsのid、および navigationParamsのナビゲーションタイミングタイプ を指定します。
登録されたハンドラーが使用される場合、新しいURLでnavigateが呼び出されます。
与えられたURLまたはレスポンス resource、ナビゲーブル navigable、サンドボックスフラグセット sandboxFlags、ブール値 hasTransientActivation、およびオリジン initiatorOriginが与えられた場合、外部ソフトウェアに引き渡すためには、ユーザーエージェントは次を行うべきです:
次のすべてが真である場合:
navigableがトップレベルトラバース可能なナビゲーブルではない。
sandboxFlagsにサンドボックス化されたカスタムプロトコルナビゲーションブラウジングコンテキストフラグが設定されている。
sandboxFlagsにサンドボックス化されたユーザーアクティベーション付きトップレベルナビゲーションブラウジングコンテキストフラグが設定されているか、hasTransientActivationが偽である。
この場合、外部ソフトウェアパッケージを起動せずに戻ります。
iframe内の外部ソフトウェアへのナビゲーションは、ユーザーに新しいポップアップまたは新しいトップレベルナビゲーションとして見える場合があります。そのため、iframe
では、次のいずれかが指定されている場合にのみ許可されます: allow-popups、
allow-top-navigation、
allow-top-navigation-by-user-activation、
またはallow-top-navigation-to-custom-protocols。
resourceの適切な引き渡しを行い、ターゲットソフトウェアを悪用しようとする試みであるリスクを軽減するよう努めます。例えば、ユーザーエージェントは、initiatorOriginが対象の外部ソフトウェアを起動することを許可するかどうかを確認するためにユーザーにプロンプトを表示することができます。特に、hasTransientActivationが偽である場合、ユーザーの事前確認なしに外部ソフトウェアパッケージを起動すべきではありません。
例えば、ターゲットソフトウェアのURLハンドラーに脆弱性があり、悪意のあるページがユーザーをリンククリックに誘導してその脆弱性を悪用しようとする可能性があります。
ナビゲーションプロセスの早い段階で介入し、全体を停止させるシナリオがいくつかあります。これは、セッション履歴のトラバースによって、複数のナビゲーブルが同時にナビゲートしている場合に特に興味深いものです。
ナビゲーブル sourceが、ソーススナップショットパラメータ sourceSnapshotParamsが与えられた場合に、2番目のナビゲーブル targetをサンドボックスによってナビゲートすることが許可されているかどうかを確認するためには、次のステップがtrueを返す必要があります:
もしsourceがtargetである場合は、trueを返します。
もしsourceがtargetの祖先である場合は、trueを返します。
もしtargetがsourceの祖先である場合は:
もしtargetがトップレベルのトラバース可能なものでない場合は、trueを返します。
もしsourceSnapshotParamsの一時的なアクティベーションがあるがtrueであり、sourceSnapshotParamsのサンドボックスフラグのユーザーアクティベーション付きトップレベルナビゲーションブラウジングコンテキストフラグが設定されている場合は、falseを返します。
もしsourceSnapshotParamsの一時的なアクティベーションがあるがfalseであり、sourceSnapshotParamsのサンドボックスフラグのユーザーアクティベーションなしトップレベルナビゲーションブラウジングコンテキストフラグが設定されている場合は、falseを返します。
trueを返します。
もしtargetがトップレベルのトラバース可能なものである場合:
もしsourceがtargetの許可された1つのサンドボックス化されたナビゲーターである場合は、trueを返します。
もしsourceSnapshotParamsのサンドボックスフラグのサンドボックス化されたナビゲーションブラウジングコンテキストフラグが設定されている場合は、falseを返します。
trueを返します。
もしsourceSnapshotParamsのサンドボックスフラグのサンドボックス化されたナビゲーションブラウジングコンテキストフラグが設定されている場合は、falseを返します。
trueを返します。
ドキュメントのアンロードがキャンセルされたかどうかを確認するために、オプションのトラバース可能なナビゲーブル
traversable、オプションの整数targetStep、およびオプションのユーザーのナビゲーション関与-or-null
userInvolvementForNavigateEventが与えられたリストのナビゲーブル
navigablesThatNeedBeforeUnloadについて、次の手順を実行します。これらは、"canceled-by-beforeunload"、"canceled-by-navigate"、または"continue"を返します。
navigablesThatNeedBeforeUnload内の各項目のアクティブなドキュメントをdocumentsToFireBeforeunloadとします。
unloadPromptShownをfalseに設定します。
finalStatusを"continue"に設定します。
もしtraversableが与えられた場合は:
アサート: targetStepおよびuserInvolvementForNavigateEventが与えられた。
traversableおよびtargetStepを指定してターゲット履歴エントリを取得する結果をtargetEntryとします。
もしtargetEntryがtraversableの現在のセッション履歴エントリでなく、targetEntryのドキュメント状態のオリジンがtraversableの現在のセッション履歴エントリのドキュメント状態のオリジンと同じである場合は:
この場合、ここでtraversableのnavigateイベントを発生させるつもりです。ある状況下ではキャンセルされる可能性があるため、これは他のトラバースnavigateイベントとは別に行う必要があります。
さらに、beforeunloadイベントをnavigateイベントの前に発生させたいので、traversableに対して(該当する場合)ここでbeforeunloadを発生させる必要があります。これをdocumentsToFireBeforeunloadに対する以下のループの一部として行うのではなく。
アサート: userInvolvementForNavigateEventがnullでない。
eventsFiredをfalseに設定します。
もしnavigablesThatNeedBeforeUnloadがtraversableを含んでいる場合、needsBeforeunloadをtrueに設定し、それ以外の場合はfalseに設定します。
もしneedsBeforeunloadがtrueである場合は、traversableのアクティブドキュメントをdocumentsToFireBeforeunloadから削除します。
traversableのアクティブウィンドウに対して、次の手順を実行するために、グローバルタスクをキューに入れます:
もしneedsBeforeunloadがtrueである場合は:
(unloadPromptShownForThisDocument、unloadPromptCanceledByThisDocument)をtraversableのアクティブドキュメントを与えて、beforeunloadを発生させる手順を実行した結果とします。
もしunloadPromptShownForThisDocumentがtrueである場合は、unloadPromptShownをtrueに設定します。
もしunloadPromptCanceledByThisDocumentがtrueである場合は、finalStatusを"canceled-by-beforeunload"に設定します。
もしfinalStatusが"canceled-by-beforeunload"である場合は、これらの手順を中止します。
traversableのアクティブウィンドウのナビゲーションAPIをnavigationとします。
targetEntryおよびuserInvolvementForNavigateEventを指定して、navigationでトラバースnavigateイベントを発生させる結果をnavigateEventResultとします。
もしnavigateEventResultがfalseである場合は、finalStatusを"canceled-by-navigate"に設定します。
eventsFiredをtrueに設定します。
eventsFiredがtrueになるまで待機します。
もしfinalStatusが"continue"でない場合は、finalStatusを返します。
documentsThatNeedBeforeunloadのサイズをtotalTasksとします。
completedTasksを0に設定します。
documentsの各documentについて、documentの関連するグローバルオブジェクトに対して、次の手順を実行するために、グローバルタスクをキューに入れます:
(unloadPromptShownForThisDocument、unloadPromptCanceledByThisDocument)をdocumentおよびunloadPromptShownを与えて、beforeunloadを発生させる手順を実行した結果とします。
もしunloadPromptShownForThisDocumentがtrueである場合は、unloadPromptShownをtrueに設定します。
もしunloadPromptCanceledByThisDocumentがtrueである場合は、finalStatusを"canceled-by-beforeunload"に設定します。
completedTasksを1増加させます。
completedTasksがtotalTasksになるまで待機します。
finalStatusを返します。
beforeunloadを発生させる手順は、Document
documentおよびブール値unloadPromptShownを与えて、次の通りです:
unloadPromptCanceledをfalseに設定します。
documentのアンロードカウンターを1増加させます。
documentの関連するエージェントのイベントループの終了ネスティングレベルを1増加させます。
documentの関連するグローバルオブジェクトで、キャンセル可能属性がtrueに初期化されたBeforeUnloadEventを使用して、beforeunloadという名前のイベントを発生させる結果をeventFiringResultとします。
documentの関連するエージェントのイベントループの終了ネスティングレベルを1減少させます。
次のすべてが真である場合:
unloadPromptShownがfalseである。
documentのアクティブサンドボックスフラグセットにサンドボックス化されたモーダルフラグが設定されていない。
documentの関連するグローバルオブジェクトにスティッキーアクティベーションがある。
eventFiringResultがfalseであるか、またはeventのreturnValue属性が空文字列でない。
アンロードプロンプトの表示が迷惑、欺瞞、または無意味である可能性が低い。
次のことを行います:
unloadPromptShownをtrueに設定します。
documentの関連するグローバルオブジェクト、"beforeunload"、および""を使用して、WebDriver BiDiユーザープロンプトが開かれましたを呼び出します。
ドキュメントをアンロードすることを確認するようユーザーに尋ね、ユーザーの応答を待つ間一時停止します。
ユーザーに表示されるメッセージはカスタマイズできず、ユーザーエージェントによって決定されます。特に、returnValue属性の実際の値は無視されます。
もしユーザーがページナビゲーションを確認しなかった場合は、unloadPromptCanceledをtrueに設定します。
documentの関連するグローバルオブジェクトとともに、unloadPromptCanceledがfalseの場合はtrueを、それ以外の場合はfalseを使用して、WebDriver BiDiユーザープロンプトが閉じられましたを呼び出します。
documentのアンロードカウンターを1減少させます。
(unloadPromptShown、unloadPromptCanceled)を返します。
進行中のナビゲーションを設定するためには、ナビゲーブル navigableにnewValueを設定します:
もしnavigableの進行中のナビゲーションがnewValueと等しい場合は、終了します。
ナビゲーションの中止についてナビゲーションAPIに通知をnavigableに対して実行します。
navigableの進行中のナビゲーションをnewValueに設定します。
リロードするためには、オプションのシリアライズされた状態またはnull navigationAPIState(デフォルトはnull)およびオプションのユーザーのナビゲーション関与
userInvolvement(デフォルトは"none")が与えられたナビゲーブル navigableをリロードします:
もしuserInvolvementが"browser UI"でない場合は:
navigableのアクティブウィンドウのナビゲーションAPIをnavigationとします。
navigableのアクティブなセッション履歴エントリのナビゲーションAPI状態をdestinationNavigationAPIStateとします。
もしnavigationAPIStateがnullでない場合は、destinationNavigationAPIStateをnavigationAPIStateに設定します。
navigationでpush/replace/reload
navigateイベントを発生させる結果をcontinueとします。その際、navigationTypeを"reload"、isSameDocumentをfalse、userInvolvementをuserInvolvement、destinationURLをnavigableのアクティブなセッション履歴エントリのURL、およびnavigationAPIStateをdestinationNavigationAPIStateに設定します。
もしcontinueがfalseである場合は、終了します。
navigableのアクティブなセッション履歴エントリのドキュメント状態のリロード保留中をtrueに設定します。
navigableのトラバース可能なナビゲーブルをtraversableとします。
traversableに次のセッション履歴トラバースステップを追加します:
traversableにリロード履歴ステップを適用します。
履歴をデルタでトラバースするためには、トラバース可能なナビゲーブル
traversable、整数delta、およびオプションのDocument sourceDocumentが与えられた場合に次を行います:
sourceSnapshotParamsおよびinitiatorToCheckをnullとします。
userInvolvementを"ブラウザUI"とします。
もしsourceDocumentが与えられた場合は:
sourceDocumentを与えてソーススナップショットパラメータをスナップショットする結果をsourceSnapshotParamsとします。
sourceDocumentのノードナビゲーブルをinitiatorToCheckとします。
userInvolvementを"none"とします。
traversableに次のセッション履歴トラバースステップを追加します:
traversableに対して使用されたすべての履歴ステップを取得する結果をallStepsとします。
traversableの現在のセッション履歴ステップのインデックスをallSteps内のcurrentStepIndexとします。
currentStepIndexにdeltaを加えたものをtargetStepIndexとします。
もしallSteps[targetStepIndex]が存在しない場合は、これらのステップを中止します。
sourceSnapshotParams、initiatorToCheck、およびuserInvolvementを指定して、traversableにallSteps[targetStepIndex]にトラバース履歴ステップを適用します。
ナビゲートアルゴリズムとは別に、セッション履歴エントリはもう一つのメカニズムでプッシュまたは置換されることがあり、それがURLおよび履歴更新ステップです。これらのステップの最もよく知られている呼び出し元は、history.replaceState()およびhistory.pushState()APIですが、標準のさまざまな他の部分もアクティブな履歴エントリの更新を行う必要があり、それらはこれらのステップを使用してそれを行います。
URLおよび履歴更新ステップでは、Document document、URL
newURL、オプションのシリアライズされた状態またはnull serializedData(デフォルトはnull)、およびオプションの履歴処理動作 historyHandling(デフォルトは"replace")が与えられます:
documentのノードナビゲーブルをnavigableとします。
navigableのアクティブなセッション履歴エントリをactiveEntryとします。
newEntryを新しいセッション履歴エントリとして作成し、以下のプロパティを設定します。
もしdocumentの初期about:blankであるがtrueの場合は、historyHandlingを"replace"に設定します。
これは、pushState()が初期about:blankDocumentで呼び出された場合、replaceState()の呼び出しとして動作することを意味します。
historyHandlingが"replace"である場合はentryToReplaceをactiveEntryに設定し、それ以外の場合はnullとします。
もしhistoryHandlingが"push"である場合は:
これらは、即時の同期アクセスのための一時的な推測値です。
もしserializedDataがnullでない場合は、履歴オブジェクト状態を復元してdocumentとnewEntryを与えます。
documentのURLをnewURLに設定します。
これはナビゲーションでも履歴のトラバースでもないため、hashchangeイベントは発生しません。
documentの最新のエントリをnewEntryに設定します。
navigableのアクティブなセッション履歴エントリをnewEntryに設定します。
同じドキュメント内のナビゲーションのためにナビゲーションAPIエントリを更新しますを、documentの関連するグローバルオブジェクトのナビゲーションAPI、newEntry、およびhistoryHandlingに対して実行します。
navigableのトラバース可能なナビゲーブルをtraversableとします。
traversableに関連する次のセッション履歴同期ナビゲーションステップを追加し、navigableに適用します:
traversable、navigable、newEntry、entryToReplace、およびhistoryHandlingを指定して同じドキュメント内のナビゲーションを確定します。
フラグメントナビゲーションとURLおよび履歴更新ステップの両方が同期履歴更新を行いますが、フラグメントナビゲーションのみが履歴ステップ適用のためのドキュメントを更新の同期呼び出しを含みます。URLおよび履歴更新ステップは、上記のアルゴリズム内でいくつかの選択された更新を実行し、他の更新を省略します。これは歴史的な不運な事故のようなものであり、一般的にウェブ開発者の悲しみを引き起こす一因となっています。例えば、これにより、popstateイベントはフラグメントナビゲーションでは発生しますが、history.pushState()呼び出しでは発生しません。
概要で説明されているように、ナビゲーションとトラバースの両方が、セッション履歴エントリを作成し、その後ドキュメントメンバーを設定しようとします。これにより、ナビゲーブル内で表示できるようになります。
これは、既に与えられたレスポンスを使用する、srcdocリソースを使用する、またはフェッチすることが含まれます。このプロセスには、いくつかの失敗モードがあり、それらはナビゲーブルを現在のアクティブなDocumentに留めるか、セッション履歴エントリをエラードキュメントで設定することになります。
履歴エントリのドキュメントを設定しようとするには、セッション履歴エントリentryに対し、ナビゲーブルnavigable、NavigationTimingTypenavTimingType、ソーススナップショットパラメータsourceSnapshotParams、ターゲットスナップショットパラメータtargetSnapshotParams、オプションのナビゲーションID-またはnullnavigationId(デフォルトはnull)、オプションのナビゲーションパラメータ-またはnullnavigationParams(デフォルトはnull)、オプションの文字列cspNavigationType(デフォルトは"other")、オプションのブール値allowPOST(デフォルトはfalse)、およびオプションのアルゴリズムステップcompletionSteps(デフォルトは空のアルゴリズム)を指定します:
確認: navigationParamsがnullでない場合、navigationParamsのレスポンスもnullでないこと。
currentBrowsingContextをnavigableのアクティブなブラウジングコンテキストとします。
もしnavigationParamsがnullの場合:
もしdocumentResourceが文字列である場合、navigationParamsを、srcdocリソースからナビゲーションパラメータを作成する結果に設定します。これにはentry、navigable、targetSnapshotParams、navigationId、およびnavTimingTypeを指定します。
それ以外の場合、次のすべてがtrueである場合:
documentResourceがnullであるか、allowPOSTがtrueであり、documentResourceのリクエストボディが失敗していない。
次にnavigationParamsを、フェッチによるナビゲーションパラメータの作成の結果に設定します。これにはentry、navigable、sourceSnapshotParams、targetSnapshotParams、cspNavigationType、navigationId、およびnavTimingTypeを指定します。
それ以外の場合、もしentryのURLのスキームがフェッチスキームでない場合、navigationParamsを新しい非フェッチスキームナビゲーションパラメータに設定します。
セッション履歴エントリ
entry、ナビゲーブル
navigable、ターゲットスナップショットパラメータ
targetSnapshotParams、ナビゲーションID-またはnull navigationId、および
NavigationTimingType
navTimingType が与えられた場合、 srcdocリソースからナビゲーションパラメータを作成するには、次の手順を実行します。
response を次のプロパティを持つ新しい レスポンス として設定します:
about:srcdoc
Content-Type`,
`text/html`) »
responseOrigin を response の URL、targetSnapshotParams の サンドボックスフラグ、および entry の ドキュメント状態 の オリジン を指定して オリジンを決定する の結果に設定します。
coop を新しい クロスオリジンオープナーポリシー に設定します。
coopEnforcementResult を次のプロパティを持つ新しい クロスオリジンオープナーポリシー執行結果 として設定します:
policyContainer を response の URL、entry の ドキュメント状態 の 履歴ポリシーコンテナ、null、navigable の コンテナドキュメント の ポリシーコンテナ、およびnullを指定して ナビゲーションパラメータポリシーコンテナを決定する の結果に設定します。
次のプロパティを持つ新しい ナビゲーションパラメータ を返します:
このアルゴリズムは entry を変更します。
request を新しい リクエスト に設定します。その設定は次のとおりです:
document"
include"
manual"
navigate"
もし documentResource が POST リソース である場合は:
もし entry の ドキュメント状態 の リロード保留 が true なら、request の リロードナビゲーションフラグ を設定します。
その他の場合、もし entry の ドキュメント状態 の 以前にポピュレートされた が true なら、request の 履歴ナビゲーションフラグ を設定します。
もし sourceSnapshotParams の 一時的なアクティベーションがある が true なら、request の ユーザーアクティベーション を true に設定します。
もし navigable の コンテナ が null でないなら:
もし navigable の コンテナ に 閲覧コンテキストスコープの起源 がある場合、request の 起源 をその 閲覧コンテキストスコープの起源 に設定します。
もし sourceSnapshotParams の フェッチクライアント が navigable の コンテナドキュメント の 関連設定オブジェクト なら、request の イニシエータタイプ を navigable の コンテナ の ローカル名 に設定します。
これは、コンテナによって開始されたナビゲーションのみがリソースタイミングに報告されることを保証します。
response を null に設定します。
responseOrigin を null に設定します。
fetchController を null に設定します。
coopEnforcementResult を新しい クロスオリジンオープナーポリシー実施結果 に設定します。その設定は次のとおりです:
finalSandboxFlags を空の サンドボックスフラグセット に設定します。
responsePolicyContainer を null に設定します。
responseCOOP を新しい クロスオリジンオープナーポリシー に設定します。
locationURL を null に設定します。
currentURL を request の 現在のURL に設定します。
commitEarlyHints を null に設定します。
「true」として繰り返し:
もし request の 予約済みクライアント が null でなく、かつ currentURL の 起源 が request の 予約済みクライアント の 作成URL の 起源 と同一でないなら:
環境破棄手順 を request の 予約済みクライアント のために実行します。
request の 予約済みクライアント を null に設定します。
commitEarlyHints を null に設定します。
早期ヒントヘッダー からプリロードされたリンクは、同一オリジン のリダイレクト後もプリロードキャッシュに残りますが、リダイレクトがクロスオリジンの場合には破棄されます。
もし request の 予約済みクライアント が null なら:
topLevelCreationURL を currentURL に設定します。
topLevelOrigin を null に設定します。
もし navigable が トップレベルトラバーサブル でないなら:
parentEnvironment を navigable の 親 の アクティブドキュメント の 関連設定オブジェクト に設定します。
topLevelCreationURL を parentEnvironment の トップレベル作成URL に設定します。
topLevelOrigin を parentEnvironment の トップレベル起源 に設定します。
request の 予約済みクライアント を、新しい 環境 に設定します。そのIDは一意な不透明な文字列であり、ターゲット閲覧コンテキストは navigable の アクティブな閲覧コンテキスト、作成URLは currentURL、トップレベル作成URLは topLevelCreationURL、そしてトップレベル起源は topLevelOrigin に設定されます。
作成された環境の アクティブなサービスワーカー は、リクエストURLがサービスワーカー登録に一致する場合、フェッチの際に設定されます。[SW]
もし この種類のナビゲーションリクエストがコンテンツセキュリティポリシーによってブロックされるべきか?
の結果が「Blocked」なら、response を ネットワークエラー に設定し、ループを終了します。
[CSP]
response を null に設定します。
もし fetchController が null なら、次の設定で フェッチ の結果として fetchController を設定します。プロセス早期ヒントレスポンス を processEarlyHintsResponse として以下で定義し、プロセスレスポンス を以下で定義された processResponse として設定し、並行キューを使用する を true に設定します。
processEarlyHintsResponse を レスポンス の earlyResponse に対して次のアルゴリズムに設定します:
もし commitEarlyHints が null なら、それを earlyResponse と request の 予約済みクライアント に与えられた 早期ヒントヘッダーを処理する の結果に設定します。
processResponse を レスポンス の fetchedResponse に対して次のアルゴリズムに設定します:
response を fetchedResponse に設定します。
それ以外の場合、次の手動リダイレクトを処理します fetchController に対して。
これにより、上記のループを最初に繰り返したときに提供した プロセスレスポンス が呼び出され、その結果として response が設定されます。
ナビゲーションは mailto:
URL などにリダイレクトされる唯一のウェブプラットフォームであるため、リダイレクトを手動で処理します。
response が null であるか、または navigable の 進行中のナビゲーション が navigationId と異なる状態に変化するまで待ちます。
後者の条件が発生した場合、フェッチを中止します fetchController をして、終了します。
それ以外の場合は、続行します。
もし request の 本文 が null なら、entry の ドキュメント状態 の リソース を null に設定します。
フェッチは特定のリダイレクトに対して本文を解除します。
responsePolicyContainer を、response および request の 予約済みクライアント に基づいて フェッチレスポンスからポリシーコンテナを作成する の結果に設定します。
finalSandboxFlags を、targetSnapshotParams の サンドボックスフラグ と responsePolicyContainer の CSPリスト の CSP由来のサンドボックスフラグ の和に設定します。
responseOrigin を response の URL、finalSandboxFlags、および entry の ドキュメント状態 の イニシエータオリジン に基づいて 起源を決定する の結果に設定します。
もし response がリダイレクトである場合、response の URL はリダイレクト先の URL ではなく、リダイレクトに繋がった URL になります。
もし navigable が トップレベルトラバーサブル なら:
responseCOOP を、response および request の 予約済みクライアント に基づいて クロスオリジンオープナーポリシーを取得する の結果に設定します。
coopEnforcementResult を、navigable の アクティブな閲覧コンテキスト、response の URL、responseOrigin、responseCOOP、coopEnforcementResult および request の リファラー に基づいて クロスオリジンオープナーポリシーを施行する の結果に設定します。
もし finalSandboxFlags が空でなく、responseCOOP の 値 が「unsafe-none」でない場合、response を適切な ネットワークエラー に設定し、ループを終了します。
これは、クロスオリジンオープナーポリシーを使用してレスポンスにクリーンスレートを提供し、そのレスポンスにナビゲートする結果をサンドボックス化できないため、ネットワークエラーとして扱われます。
もし response が ネットワークエラー でなく、navigable が 子ナビゲーブル であり、navigable の コンテナドキュメント の 起源、navigable の コンテナドキュメント の 関連設定オブジェクト、request の 送信先、および response に基づく クロスオリジンリソースポリシーチェック の結果がブロックされた場合、response を ネットワークエラー に設定し、ループを終了します。
ここでは、navigable 自身ではなく、親ナビゲーブルに対して クロスオリジンリソースポリシーチェック を実行しています。これは、埋め込まれたコンテンツの同一オリジン性がナビゲーションソースではなく親コンテキストに対して重要であるためです。
locationURL を response の ロケーションURL の currentURL の フラグメント に基づいて設定します。
もし locationURL が失敗または null なら、ループを終了します。
entry の クラシック履歴API状態 を StructuredSerializeForStorage(null) に設定します。
oldDocState を entry の ドキュメント状態 に設定します。
entry の ドキュメント状態 を新しい ドキュメント状態 に設定し、その設定は次のとおりです:
ナビゲーションの場合、oldDocState は、ナビゲートアルゴリズムの早い段階 で作成されたもので、entry のみが参照します。したがって、ナビゲーションの場合、これは実際には entry の ドキュメント状態 の更新に過ぎません。トラバーサルの場合、隣接する セッション履歴エントリ も oldDocState を参照している可能性があり、この場合、entry の ドキュメント状態 を更新した後も引き続き参照し続けます。
トラバーサルの場合にのみ、oldDocState の 履歴ポリシーコンテナ は非nullであり、ナビゲーション中に履歴にポリシーコンテナを保存する必要があるURLにナビゲートした後でポピュレートされます。
セットアップは次の ジェイク図 によって与えられます:
| 0 | 1 | 2 | 3 | |
|---|---|---|---|---|
top
| /a | /a#foo | /a#bar | /b |
また、ステップ0、1、2にあるエントリが共有する ドキュメント状態 の ドキュメント が nullであることを仮定します。すなわち、bfcache が適用されていません。
次に、ステップ2に戻ってトラバースするシナリオを考えますが、今回は/a をフェッチする際、サーバーが /c を指す
`Location` ヘッダーで応答します。つまり、locationURL が /c
を指しており、このステップに到達しました。ループから 抜ける ことなく。
この場合、ステップ2を占める ドキュメント状態 を置き換えますが、ステップ0および1を占めるエントリのドキュメント状態は置き換えません。結果の ジェイク図 は次のようになります:
| 0 | 1 | 2 | 3 | |
|---|---|---|---|---|
top
| /a | /a#foo | /c#bar | /b |
この置換は、/c 自体が /a を指す `Location` ヘッダーを持っていた場合など、元の URL
にリダイレクトチェーンで戻る場合でも実行されます。このような場合、結果は次のようになります:
| 0 | 1 | 2 | 3 | |
|---|---|---|---|---|
top
| /a | /a#foo | /a#bar | /b |
もし locationURL の スキーム が HTTP(S) スキーム でないなら:
currentURL を locationURL に設定します。
entry の URL を currentURL に設定します。
もし locationURL が URL で、その スキーム が フェッチスキーム でないなら、新しい 非フェッチスキームナビゲーションパラメータ を次の設定で返します:
この時点で、request の 現在の URL は、非 フェッチスキーム にリダイレクトされる前の、フェッチスキームを持つリダイレクトチェーンの最後の URL です。これが、非 フェッチスキーム の URL へのナビゲーションのために使用されるイニシエータオリジンになります。
次のいずれかが真の場合:
その場合、null を返します。
非 フェッチスキーム URL へのリダイレクトは許可されますが、非 HTTP(S) 以外の フェッチスキーム を持つ URL へのリダイレクトは、ネットワークエラーとして扱われます。
resultPolicyContainer を、response の URL、entry の ドキュメント状態 の 履歴ポリシーコンテナ、sourceSnapshotParams の ソースポリシーコンテナ、null、および responsePolicyContainer を与えた結果として設定します。
もしnavigableのコンテナがiframeであり、responseのタイミング許可パスフラグが設定されている場合、コンテナの保留中のリソースタイミング開始時間をnullに設定します。
もし iframe
がリソースタイミングに報告することが許可されている場合、通常の報告が行われるため、フォールバックステップを実行する必要はありません。
新しい ナビゲーションパラメータ を次の設定で返します:
要素には、ブラウジングコンテキストスコープのオリジンがあり、その要素の
Documentの
ノードナビゲーブルが
トップレベルトラバーサブルである場合、またはその要素の
Documentの
祖先ナビゲーブルがすべて、
アクティブドキュメントを持ち、それらの
オリジンが、
要素の
ノードドキュメントの
オリジンと
同一である場合です。要素が
ブラウジングコンテキストスコープのオリジン
を持っている場合、その値は要素の
オリジン
です。
この定義は壊れており、意図された内容を確認するために調査が必要です: issue #4703を参照してください。
ドキュメントの読み込みを行うには、
ナビゲーションパラメータ
navigationParams、
ソーススナップショットパラメータ
sourceSnapshotParams、
および
オリジン
initiatorOriginを指定して、次の手順を実行します。これにより、
Documentまたはnullが返されます。
ユーザーエージェントが指定されたtypeのリソースを処理するために、ナビゲーブル でコンテンツをレンダリングする以外のメカニズムを使用するように設定されている場合、このステップをスキップします。そうでない場合、typeが次のいずれかのタイプである場合:
text/css"
text/plain"
text/vtt"
multipart/x-mixed-replace"
application/pdf"
text/pdf"
それ以外の場合は先に進みます。
明示的にサポートされているXML MIMEタイプとは、
ユーザーエージェントがコンテンツをレンダリングするために外部アプリケーションを使用するように設定されているか、専用の処理ルールを持つ
XML MIMEタイプ
のことを指します。たとえば、Atomフィードビューアが組み込まれているWebブラウザは、
application/atom+xml
MIMEタイプを明示的にサポートしていると言えます。
明示的にサポートされているJSON MIMEタイプとは、 ユーザーエージェントがコンテンツをレンダリングするために外部アプリケーションを使用するように設定されているか、専用の処理ルールを持つ JSON MIMEタイプ のことを指します。
両方の場合で、外部アプリケーションまたはユーザーエージェントは、navigationParamsのナビゲーブルに直接インラインでコンテンツを表示するか、外部ソフトウェアに引き渡すことになります。どちらも以下のステップで行われます。
それ以外の場合、ドキュメントのtypeは、リソースがnavigationParamsのナビゲーブルに影響を与えないような種類である、たとえばリソースが外部アプリケーションに引き渡されるか、ダウンロードとして処理される、または未知のタイプであるためです。外部ソフトウェアに引き渡すのは、navigationParamsのレスポンス、navigationParamsのナビゲーブル、navigationParamsの最終サンドボックスフラグセット、sourceSnapshotParamsの一時的なアクティベーションを持つかどうか、およびinitiatorOriginが指定されている場合です。
nullを返します。
ナビゲーションとトラバーサルの両方において、セッション履歴で進むべき場所が決まったら、その概念をトラバーサブルナビゲーブルおよび関連するドキュメントに適用する作業が主となります。ナビゲーションの場合、この作業は通常プロセスの終わりに行われ、トラバーサルの場合はその始まりとなります。
トラバーサブルが正しいセッション履歴ステップに到達することを保証するのは特に複雑です。これは、トラバーサブルの複数のナビゲーブルの子孫を調整し、並行してポピュレートし、その後結果が全員に同じように見えることを同期する必要があるためです。このプロセスは、同一ドキュメントの同期ナビゲーションとクロスドキュメントのナビゲーションが混在し、ウェブページが特定のタイミングに対して一定の期待を持つようになったことによってさらに複雑になります。
ナビゲーブルの連続状態を変更することは、履歴ステップの適用アルゴリズム中に情報を保持するために使用され、アルゴリズムの一部が他の部分が終了した後にのみ続行できるようにします。これは以下の要素を持つ構造体です:
ドキュメント
すべてのトラバーサブルナビゲーブルの更新は、同じ履歴ステップの適用アルゴリズムに終わりますが、各エントリポイントにはいくつかのカスタマイズが含まれます:
トラバーサブルナビゲーブルのtraversableが与えられたときのナビゲーブルの作成/破棄のための更新:
stepをtraversableの現在のセッション履歴ステップとする。
履歴ステップを適用した結果をstepとしてtraversableに返し、false、null、null、null、およびnullを与える。
プッシュ/置換履歴ステップの適用において、非負整数stepが与えられ、履歴処理の動作のhistoryHandlingをトラバーサブルナビゲーブルのtraversableに適用する:
履歴ステップを適用した結果をstepとしてtraversableに返し、false、null、null、null、およびhistoryHandlingを与える。
プッシュ/置換履歴ステップの適用は、ソーススナップショットパラメータや、イニシエーターナビゲーブルを履歴ステップを適用するために渡しません。これは、これらのチェックがナビゲーションアルゴリズムの以前の段階で行われるためです。
リロード履歴ステップの適用において、トラバーサブルナビゲーブルのtraversableに適用する:
stepをtraversableの現在のセッション履歴ステップとする。
履歴ステップを適用した結果をstepとしてtraversableに返し、true、null、null、null、および"リロード"を与える。
リロード履歴ステップの適用は、ソーススナップショットパラメータやイニシエーターナビゲーブルを履歴ステップを適用するために渡しません。これは、リロードが常にそれが行われたかのように扱われるためです。ナビゲーブル自体がそうである場合でも、parent.location.reload()のようなケースにおいても。
トラバース履歴ステップの適用において、非負整数stepが与えられ、ソーススナップショットパラメータのsourceSnapshotParams、ナビゲーブルのinitiatorToCheck、およびユーザーのナビゲーション関与のuserInvolvementと共にトラバーサブルナビゲーブルのtraversableに適用する:
履歴ステップを適用した結果をstepとしてtraversableに返し、true、sourceSnapshotParams、initiatorToCheck、userInvolvement、および"トラバース"を与える。
では、アルゴリズム自体に進みましょう。
履歴ステップの適用において、非負整数stepが与えられ、トラバーサブルナビゲーブルのtraversable、ブール値のcheckForCancelation、ソーススナップショットパラメータかnullのsourceSnapshotParams、ナビゲーブルかnullのinitiatorToCheck、ユーザーナビゲーション関与かnullのuserInvolvementForNavigateEvents、およびナビゲーションタイプかnullのnavigationTypeが与えられ、以下のステップを実行します。それらは"initiator-disallowed"、"canceled-by-beforeunload"、"canceled-by-navigate"、または"applied"を返します。
アサート:これはtraversableのセッション履歴トラバーサルキュー内で実行されています。
targetStepを使用されるステップを取得する結果としてtraversableとstepに与える。
もしinitiatorToCheckがnullでない場合、次のステップを実行する:
アサート: sourceSnapshotParamsがnullでないこと。
各ナビゲーブルについて現在のセッション履歴エントリが変更またはリロードされるすべてのナビゲーブルを取得するために:initiatorToCheckがサンドボックスによってナビゲートが許可されているかどうかをナビゲーブルに対してsourceSnapshotParamsを与えて確認し、許可されていない場合、"initiator-disallowed"を返します。
navigablesCrossingDocumentsをクロスドキュメントトラバースを経験する可能性のあるすべてのナビゲーブルを取得する結果としてtraversableとtargetStepに与える。
もしcheckForCancelationがtrueであり、navigablesCrossingDocuments、traversable、targetStep、およびuserInvolvementForNavigateEventsが与えられたとき、アンロードがキャンセルされているかどうかを確認する結果が"continue"でない場合、その結果を返します。
changingNavigablesを現在のセッション履歴エントリが変更またはリロードされるすべてのナビゲーブルを取得する結果としてtraversableとtargetStepに与える。
nonchangingNavigablesThatStillNeedUpdatesを履歴オブジェクトの長さ/インデックス更新のみが必要なすべてのナビゲーブルを取得する結果としてtraversableとtargetStepに与える。
各ナビゲーブルについて、changingNavigablesを:
targetEntryをターゲット履歴エントリを取得する結果としてナビゲーブルとtargetStepに与える。
ナビゲーブルの現在のセッション履歴エントリをtargetEntryに設定する。
進行中のナビゲーションを設定するをナビゲーブルに対して"トラバース"に設定する。
totalChangeJobsをサイズのchangingNavigablesに設定する。
completedChangeJobsを0に設定する。
changingNavigableContinuationsを空のキューとしてchangingNavigableContinuationsのナビゲーブルの連続状態を変更するに設定する。
このキューはchangingNavigablesの操作を2つの部分に分割するために使用されます。特にchangingNavigableContinuationsは2番目の部分のデータを保持します。
各ナビゲーブルについて、changingNavigablesを:グローバルタスクをキューに追加し、ナビゲーブルのアクティブウィンドウのナビゲーションとトラバーサルのタスクソースで実行するステップとして設定する:
この一連のステップは、ドキュメントがアンロードされる前に同期ナビゲーションを処理できるように2つの部分に分割されます。状態はchangingNavigableContinuationsに保存され、2番目の部分で使用されます。
displayedEntryをナビゲーブルのアクティブなセッション履歴エントリに設定する。
targetEntryをナビゲーブルの現在のセッション履歴エントリに設定する。
changingNavigableContinuationをナビゲーブルの連続状態を変更するとして次の要素を持つように設定する:
もしdisplayedEntryがtargetEntryであり、targetEntryのドキュメント状態のリロード保留中がfalseである場合:
changingNavigableContinuationの更新のみをtrueに設定する。
キューに追加するchangingNavigableContinuationをchangingNavigableContinuationsに。
これらのステップを中止する。
このケースは、同期ナビゲーションがすでにアクティブなセッション履歴エントリを更新した結果として発生します。
navigationTypeに応じてスイッチ:
もしtargetEntryのドキュメントがnullである場合、またはtargetEntryのドキュメント状態のリロード保留中がtrueである場合、次のステップを実行:
navTimingTypeを次のように設定する:戻る/進むがtargetEntryのドキュメントがnullの場合、それ以外の場合は"リロード"。
targetSnapshotParamsをターゲットスナップショットパラメータのスナップショット結果としてナビゲーブルに与える。
potentiallyTargetSpecificSourceSnapshotParamsをsourceSnapshotParamsに設定する。
もしpotentiallyTargetSpecificSourceSnapshotParamsがnullの場合、それをソーススナップショットパラメータのスナップショット結果としてナビゲーブルのアクティブドキュメントに設定する。
このケースでは、トラバース/リロードの明確なソースはありません。ナビゲーブルが自分自身をナビゲートしたかのように扱いますが、targetEntryの元のイニシエーターの一部のプロパティはtargetEntryのドキュメント状態に保存され、イニシエーターのオリジンやリファラーなど、ナビゲーションに適切な影響を与えます。
並行して履歴エントリのドキュメントをポピュレートするための試みをtargetEntry、ナビゲーブル、potentiallyTargetSpecificSourceSnapshotParams、targetSnapshotParamsに対して行い、allowPOSTをallowPOSTに設定し、完了ステップをナビゲーブルのアクティブウィンドウに対してグローバルタスクをキューに追加することでafterDocumentPopulatedを実行する。
それ以外の場合、即座にafterDocumentPopulatedを実行する。
どちらの場合でも、afterDocumentPopulatedを以下のステップとして設定する:
もしtargetEntryのドキュメントがnullである場合、changingNavigableContinuationの更新のみをtrueに設定する。
これは、ドキュメントをポピュレートしようとしたが、例えばサーバーが204を返すなどして、それができなかったことを意味します。
このようなナビゲーションやトラバーサルの失敗は、ナビゲーションAPIに通知されません(例えば、任意のナビゲーションAPIメソッドトラッカーのプロミスや、navigateerrorイベントを通じて)。これを行うと、クロスオリジンの場合に他のオリジンからのレスポンスのタイミングに関する情報が漏洩する可能性があり、クロスオリジンと同一オリジンの場合で異なる結果を提供することは混乱を招くと考えられました。
しかし、この機会を利用して、navigation.transition.finishedプロミスのハンドラーをクリアすることができます。これらはこの時点で決して実行されないことが保証されています。また、ナビゲーションAPIのいずれかがこれらのナビゲーションを開始した場合、プロミスが決して解決されず、イベントが発生しない理由をウェブ開発者に明確にするために、コンソールに警告を報告することを検討するかもしれません。
もしtargetEntryのドキュメントのオリジンがoldOriginと異なる場合、targetEntryのクラシック履歴API状態をStructuredSerializeForStorage(null)に設定します。
これは、リダイレクトが発生しなかった場合に、targetEntryの以前のロードとオリジンが変更されたときに履歴状態をクリアします。これはCSPサンドボックスヘッダーの変更によって発生することがあります。
次のすべてがtrueである場合:
ナビゲーブルの親がnullである場合;
targetEntryのドキュメントのブラウジングコンテキストが補助ブラウジングコンテキストではなく、かつそのオープナー・ブラウジング・コンテキストが非nullである場合;
その場合、targetEntryのドキュメント状態のナビゲーブルターゲット名を空文字列に設定する。
キューに追加するchangingNavigableContinuationをchangingNavigableContinuationsに。
このジョブの残りの部分は、このアルゴリズムの後の段階で実行されます。
navigablesThatMustWaitBeforeHandlingSyncNavigationを空のセットとして設定する。
completedChangeJobsがtotalChangeJobsと等しくなるまで:
もしtraversableのネストされた履歴ステップの適用を実行中がfalseである場合:
changingNavigableContinuationをデキューする結果としてchangingNavigableContinuationsから設定する。
もしchangingNavigableContinuationが何もない場合、続行する。
displayedDocumentをchangingNavigableContinuationの表示されたドキュメントとして設定する。
targetEntryをchangingNavigableContinuationのターゲットエントリとして設定する。
ナビゲーブルをchangingNavigableContinuationのナビゲーブルとして設定する。
(scriptHistoryLength, scriptHistoryIndex)を履歴オブジェクトの長さとインデックスを取得する結果としてtraversableとtargetStepに与える。
これらの値は最後に計算されたときから変わっているかもしれません。
追加するナビゲーブルをnavigablesThatMustWaitBeforeHandlingSyncNavigationに。
ナビゲーブルがトラバースのこの時点に到達したら、さらにキューに追加された同期ナビゲーションステップは、通常このトラバースの後に発生する意図があるため、キューを飛び越えなくなります。詳細はこちらをご覧ください。
entriesForNavigationAPIをナビゲーションAPI用のセッション履歴エントリを取得する結果としてナビゲーブルとtargetStepに与える。
もしchangingNavigableContinuationの更新のみがtrueである場合、またはtargetEntryのドキュメントがdisplayedDocumentである場合:
これは同一ドキュメントのナビゲーションです: アンロードせずに進行します。
進行中のナビゲーションを設定するをナビゲーブルに対してnullに設定する。
これにより、新しいナビゲーションがナビゲーブルで開始できるようになり、トラバース中にブロックされていたものが解除されます。
グローバルタスクをキューに追加し、ナビゲーブルのアクティブウィンドウに対してナビゲーションとトラバーサルのタスクソースでafterPotentialUnloadsを実行する。
それ以外の場合:
アサート: navigationTypeがnullでないこと。
クロスドキュメントナビゲーション用にドキュメントを非アクティブ化するをdisplayedDocumentに対してuserNavigationInvolvement、targetEntry、navigationType、およびafterPotentialUnloadsを与える。
どちらの場合でも、afterPotentialUnloadsを以下のステップとして設定する:
もしchangingNavigableContinuationの更新のみがfalseである場合、履歴エントリをアクティブ化するをtargetEntryのナビゲーブルに対して実行する。
updateDocumentをtargetEntryのドキュメントに対して、targetEntry、changingNavigableContinuationの更新のみ、scriptHistoryLength、scriptHistoryIndex、navigationType、entriesForNavigationAPI、およびdisplayedEntryを与えて実行するアルゴリズムステップとして設定する。
もしtargetEntryのドキュメントがdisplayedDocumentと等しい場合、updateDocumentを実行する。
それ以外の場合、グローバルタスクをキューに追加し、targetEntryのドキュメントの関連するグローバルオブジェクトに対してupdateDocumentを実行する。
completedChangeJobsをインクリメントする。
totalNonchangingJobsをサイズのnonchangingNavigablesThatStillNeedUpdatesに設定する。
このステップ以降は、同期ナビゲーションの処理など、履歴の長さとインデックスを更新するタスクをポストするため、すべての前の操作が完了するのを待つように意図されています。
completedNonchangingJobsを0に設定する。
(scriptHistoryLength, scriptHistoryIndex)を履歴オブジェクトの長さとインデックスを取得する結果としてtraversableとtargetStepに与える。
各ナビゲーブルについてnonchangingNavigablesThatStillNeedUpdatesを:グローバルタスクをキューに追加し、ナビゲーブルのアクティブウィンドウのナビゲーションとトラバーサルのタスクソースに設定し、次のステップを実行する:
ドキュメントをナビゲーブルのアクティブドキュメントに設定する。
completedNonchangingJobsをインクリメントする。
completedNonchangingJobsがtotalNonchangingJobsと等しくなるのを待つ。
traversableの現在のセッション履歴ステップをtargetStepに設定する。
"適用済み"を返す。
次のdisplayedDocument、ユーザーのナビゲーション関与 userNavigationInvolvement、セッション履歴エントリ targetEntry、NavigationType navigationType および afterPotentialUnloads という引数を受け取らないアルゴリズムで、 ドキュメントを他のドキュメントへのナビゲーションのために非アクティブにする方法は次の通りです。
navigable を displayedDocument の ノードナビゲーブル とします。
potentiallyTriggerViewTransition を false とします。
isBrowserUINavigation は userNavigationInvolvement が「ブラウザ UI」であれば
true、それ以外は false とします。
potentiallyTriggerViewTransition を次の引数を持つナビゲーションが他のドキュメントのビュー遷移をトリガーできるかの結果に設定します。 displayedDocument、targetEntry のドキュメント、navigationType、 およびisBrowserUINavigation。
もしpotentiallyTriggerViewTransition が false であれば:
firePageSwapBeforeUnload という手順を次のようにします:
pageswap イベントを displayedDocument、targetEntry、 navigationType、 および null に対して発火します。
これにより、navigable の新しいナビゲーションが開始されます。
ドキュメントとその子孫をアンロードするには、 displayedDocument、targetEntry のドキュメント、 afterPotentialUnloads、 およびfirePageSwapBeforeUnloadを与えてください。
そうでない場合は、グローバルタスクをキューに追加します navigable のアクティブウィンドウで次の手順を実行します:
proceedWithNavigationAfterViewTransitionCapture という手順を次のようにします:
セッション履歴のトラバーサル手順を追加します navigable の トラバーサブルナビゲーブル に対して次のようにします:
これにより、navigable の新しいナビゲーションが開始されます。
ドキュメントとその子孫をアンロードするには、 displayedDocument、targetEntry のドキュメント、 およびafterPotentialUnloadsを与えてください。
ドキュメント間ビュー遷移のセットアップの結果をviewTransitionに設定します。 displayedDocument、targetEntry のドキュメント、 navigationType、 およびproceedWithNavigationAfterViewTransitionCaptureを与えてください。
pageswap イベントを displayedDocument、targetEntry、navigationType、viewTransitionに対して発火します。
もしviewTransitionが null の場合は、proceedWithNavigationAfterViewTransitionCaptureを実行します。
ビュー遷移が開始された場合、ビュー遷移アルゴリズムはproceedWithNavigationAfterViewTransitionCaptureを呼び出す責任を負います。
pageswap イベントをdisplayedDocument、
セッション履歴エントリ
targetEntry、NavigationType
navigationType、およびViewTransition-または-null
viewTransitionに基づいて発火するには:
navigationをdisplayedDocumentの関連グローバルオブジェクトのナビゲーションAPIに設定します。
activationをnullに設定します。
以下のすべてが真であれば:
targetEntryのドキュメントがクロスオリジンリダイレクトによって作成されたがfalseである、またはtargetEntryのドキュメントの最新のエントリがnullでない場合。
次に:
navigationTypeに基づいてdestinationEntryを決定します:
リロード"
navigationの現在のエントリ
トラバース"
navigationのエントリリストにあるNavigationHistoryEntryのtargetEntryのセッション履歴エントリ
プッシュ"
置換"
displayedDocumentの関連するレルムに新しく作成されたNavigationHistoryEntryとし、そのセッション履歴エントリをtargetEntryに設定します。
displayedDocumentの関連するレルムで作成されたNavigationActivationの新しいインスタンスにactivationを設定し、次のプロパティを持たせます。
これは、ナビゲーション中のクロスオリジンリダイレクトが、古いドキュメントのPageSwapEventでのactivationがnullになることを意味します。ただし、新しいドキュメントがbfcacheから復元されていない限り。
イベントを発火させます。displayedDocumentの関連グローバルオブジェクトでpageswapという名前で、PageSwapEventを使用し、そのactivationをactivationに、viewTransitionをviewTransitionに設定します。
セッション履歴エントリのentryをナビゲーブルでnavigableとしてアクティブ化するには:
保存された状態を保存し、navigableのアクティブなセッション履歴エントリに追加します。
newDocumentをentryのドキュメントに設定します。
アサート: newDocumentの初期about:blankはfalseであること、すなわち、ドキュメントをナビゲートするときに常に置換されるため、初期about:blankに戻ることはありません。
navigableのアクティブなセッション履歴エントリをentryに設定します。
アクティブ化しますnewDocument。
traversableに対して非負整数のstepを指定してused stepを取得するには、次の手順を実行します。これらは非負整数を返します。
traversable内のすべての使用された履歴ステップを取得した結果をstepsに設定します。
step以下で最も大きなアイテムをstepsから返します。
これは、ナビゲーブルの削除によりセッション履歴エントリがstepを持たない場合に対応します。
トラバーサブルナビゲーブルのtraversableと非負整数のstepを指定して、履歴オブジェクトの長さとインデックスを取得するには、次の手順を実行します。これらは、2つの非負整数からなるタプルを返します。
traversable内のすべての使用された履歴ステップを取得した結果をstepsに設定します。
stepsのサイズをscriptHistoryLengthに設定します。
アサート: stepsにstepが含まれていることを確認します。
これは、stepが使用されたステップを取得によって調整されたことが前提です。
stepのstepsにおけるインデックスをscriptHistoryIndexに設定します。
(scriptHistoryLength, scriptHistoryIndex)を返します。
トラバーサブルナビゲーブルのtraversableと非負整数のtargetStepを指定して、現在のセッション履歴エントリが変更またはリロードされるすべてのナビゲーブルを取得するには、次の手順を実行します。これらは、リストのナビゲーブルを返します。
resultsを空のリストに設定します。
navigablesToCheckを« traversable »に設定します。
このリストは以下のループで拡張されます。
それぞれのnavigableに対して、navigablesToCheckをチェックします。
ターゲット履歴エントリを取得した結果をnavigableとtargetStepに基づいてtargetEntryに設定します。
もしtargetEntryがnavigableの現在のセッション履歴エントリではなく、targetEntryのドキュメント状態のリロード保留が真である場合、navigableをresultsに追加します。
もしtargetEntryのドキュメントがnavigableのドキュメントであり、targetEntryのドキュメント状態のリロード保留が偽である場合、navigableの子ナビゲーブルをnavigablesToCheckに拡張します。
子ナビゲーブルをnavigablesToCheckに追加することで、これらのナビゲーブルもこのループによってチェックされます。子ナビゲーブルは、navigableのアクティブドキュメントがこのトラバーサルの一部として変更されない場合にのみチェックされます。
resultsを返します。
トラバーサブルナビゲーブルのtraversableと非負整数のtargetStepを指定して、履歴オブジェクトの長さ/インデックスの更新のみが必要なすべてのナビゲーブルを取得するには、次の手順を実行します。これらは、リストのナビゲーブルを返します。
他のナビゲーブルは、このトラバーサルによって影響を受けない場合があります。たとえば、レスポンスが204の場合、現在アクティブなドキュメントはそのままになります。さらに、204の後に「戻る」と、現在のセッション履歴エントリは変更されますが、アクティブなセッション履歴エントリはすでに正しいです。
resultsを空のリストに設定します。
navigablesToCheckを« traversable »に設定します。
このリストは以下のループで拡張されます。
それぞれのnavigableに対して、navigablesToCheckをチェックします。
ターゲット履歴エントリを取得した結果をnavigableとtargetStepに基づいてtargetEntryに設定します。
もしtargetEntryがnavigableの現在のセッション履歴エントリであり、targetEntryのドキュメント状態のリロード保留が偽である場合:
resultsを返します。
ナビゲーブルのnavigableと非負整数のstepを指定して、ターゲット履歴エントリを取得するには、次の手順を実行します。これらは、セッション履歴エントリを返します。
navigableのセッション履歴エントリを取得した結果をentriesに設定します。
entries内のstep以下の最大のアイテムを返します。
ターゲット履歴エントリを取得が入力step以下の最大のステップを持つエントリを返す理由を見るためには、次のJakeダイアグラムを考慮してください。
| 0 | 1 | 2 | 3 | |
|---|---|---|---|---|
top
| /t | /t#foo | ||
frames[0]
| /i-0-a | /i-0-b | ||
入力ステップ1の場合、topナビゲーブルのターゲット履歴エントリはステップ0の/tエントリであり、frames[0]ナビゲーブルのターゲット履歴エントリはステップ1の/i-0-bエントリです。
| 0 | 1 | 2 | 3 | |
|---|---|---|---|---|
top
| /t | /t#foo | ||
frames[0]
| /i-0-a | /i-0-b | ||
同様に、入力ステップ3の場合、ステップ3のtopエントリとステップ1のframes[0]エントリが得られます。
| 0 | 1 | 2 | 3 | |
|---|---|---|---|---|
top
| /t | /t#foo | ||
frames[0]
| /i-0-a | /i-0-b | ||
トラバーサブルナビゲーブルのtraversableと非負整数のtargetStepを指定して、ドキュメント間トラバーサルを経験する可能性があるすべてのナビゲーブルを取得するには、次の手順を実行します。これらは、リストのナビゲーブルを返します。
traversableのセッション履歴トラバーサルキューの観点から見ると、これらのドキュメントはtargetStepで説明されるトラバーサル中にクロスドキュメント化する候補となります。ターゲットドキュメントのステータスコードがHTTP 204 No Contentである場合、それらはクロスドキュメントトラバーサルを経験しません。
特定のナビゲーブルがクロスドキュメントトラバーサルを経験する可能性がある場合、このアルゴリズムはナビゲーブルを返しますが、その子ナビゲーブルは返しません。それらはトラバーサルされず、アンロードされることになります。
resultsを空のリストに設定します。
navigablesToCheckを« traversable »に設定します。
このリストは以下のループで拡張されます。
それぞれのnavigableに対して、navigablesToCheckをチェックします。
ターゲット履歴エントリを取得した結果をnavigableとtargetStepに基づいてtargetEntryに設定します。
もしtargetEntryのドキュメントがnavigableのドキュメントでないか、targetEntryのドキュメント状態のリロード保留が真である場合、navigableをresultsに追加します。
たとえnavigableのアクティブな履歴エントリが同期的に変更されたとしても、新しいエントリは常に同じドキュメントを持つため、navigableのドキュメントにアクセスすることは信頼できます。
それ以外の場合は、navigableの子ナビゲーブルを使用してnavigablesToCheckを拡張します。
子ナビゲーブルをnavigablesToCheckに追加することで、これらのナビゲーブルもこのループによってチェックされます。子ナビゲーブルは、navigableのアクティブドキュメントがこのトラバーサルの一部として変更されない場合にのみチェックされます。
resultsを返します。
Document document、セッション履歴エントリ
entry、ブール値のdoNotReactivate、整数のscriptHistoryLengthとscriptHistoryIndex、NavigationTypeまたはnullのnavigationType、任意のリストのセッション履歴エントリ
entriesForNavigationAPI、および任意のセッション履歴エントリ
previousEntryForActivationを指定して履歴ステップ適用のためにドキュメントを更新するには、次の手順を実行します。
documentの最新エントリがnullの場合はdocumentIsNewをtrueに設定し、それ以外の場合はfalseに設定します。
documentの最新エントリがentryでない場合はdocumentsEntryChangedをtrueに設定し、それ以外の場合はfalseに設定します。
navigationをhistoryの関連グローバルオブジェクトのナビゲーションAPIに設定します。
documentsEntryChangedがtrueの場合、次の手順を実行します。
documentの最新エントリをentryに設定します。
履歴オブジェクトの状態を復元するをdocumentおよびentryに対して実行します。
documentIsNewがfalseの場合、次の手順を実行します。
アサート: navigationTypeはnullでないこと。
同一ドキュメントナビゲーションのためのナビゲーションAPIエントリを更新するをnavigation、entry、およびnavigationTypeに対して実行します。
イベントを発火する「popstate」と名付けたdocumentの関連グローバルオブジェクトに対して、PopStateEventを使用し、そのstate属性をdocumentの履歴オブジェクトのstateで初期化し、hasUAVisualTransition属性を、ユーザーエージェントによってキャッシュされたレンダリング状態を表示する視覚的な遷移が行われた場合はtrueで初期化します。
永続状態を復元するをentryに対して実行します。
oldURLのフラグメントがentryのURLのフラグメントと等しくない場合、documentの関連グローバルオブジェクトに対してイベントを発火する「hashchange」と名付けて、HashChangeEventを使用し、そのoldURL属性をoldURLのシリアライゼーションで初期化し、newURL属性をentryのURLのシリアライゼーションで初期化します。
それ以外の場合:
アサート: entriesForNavigationAPIが与えられていること。
永続状態を復元するをentryに対して実行します。
新しいドキュメントのためのナビゲーションAPIエントリを初期化するをnavigation、entriesForNavigationAPI、およびentryに対して実行します。
以下のすべてがtrueである場合:
previousEntryForActivationが与えられていること。
navigationTypeがnullでないこと。
navigationTypeが「reload」であるか、previousEntryForActivationのドキュメントがdocumentでないこと。
次の手順を実行します。
navigationのアクティベーションがnullである場合、それを新しいNavigationActivationオブジェクトに設定し、navigationの関連領域に設定します。
previousEntryIndexをpreviousEntryForActivationのナビゲーションAPIエントリインデックスを取得するの結果としてnavigation内で設定します。
previousEntryIndexが負でない場合、activationの古いエントリをnavigationのエントリリスト[previousEntryIndex]に設定します。
それ以外の場合、以下のすべてがtrueである場合:
navigationTypeが「replace」であること。
previousEntryForActivationのドキュメント状態のオリジンがdocumentのオリジンと同一オリジンであること。
previousEntryForActivationのドキュメントの初期about:blankがfalseであること。
次にactivationの古いエントリをnavigationの関連領域で新しいNavigationHistoryEntryに設定し、そのセッション履歴エントリをpreviousEntryForActivationに設定します。
activationのナビゲーションタイプをnavigationTypeに設定します。
documentIsNewがtrueの場合、次の手順を実行します。
フラグメントへのスクロールを試みるをdocumentに対して実行します。
この時点で、documentの新しく作成されたドキュメントのためのスクリプトが実行される可能性があります。
それ以外の場合、documentsEntryChangedがfalseであり、doNotReactivateがfalseの場合、次の手順を実行します。
documentsEntryChangedがfalseである理由は2つあります。1つは、bfcacheから復元しているか、または同期的にナビゲーションを完了しており、既に同期的にdocumentの最新エントリが設定されている場合です。doNotReactivate引数はこれら2つのケースを区別します。
Document documentおよびセッション履歴エントリ
entryを指定して履歴オブジェクトの状態を復元するには、次の手順を実行します。
targetRealmをdocumentの関連領域に設定します。
stateをStructuredDeserialize(entryのクラシック履歴API状態, targetRealm)で設定し、例外が発生した場合はキャッチしてstateをnullに設定します。
Document documentをアクティブにするには、次の手順を実行します。
windowをdocumentの関連グローバルオブジェクトに設定します。
documentのブラウジングコンテキストのWindowProxyの[[Window]]内部スロット値をwindowに設定します。
documentの可視性状態をdocumentのノードナビゲーブルのトラバーサブルナビゲーブルのシステム可視性状態に設定します。
新しいVisibilityStateEntryをキューに入れ、その可視性状態をdocumentの可視性状態に設定し、そのタイムスタンプをゼロに設定します。
windowの関連設定オブジェクトの実行準備フラグを設定します。
Document document、セッション履歴エントリ
reactivatedEntry、およびリストのセッション履歴エントリ entriesForNavigationAPIを指定してドキュメントを再活性化するには、次の手順を実行します。
このアルゴリズムは、documentがbfcacheから出てきた後、つまり再び完全にアクティブになった後にdocumentを更新します。この変更を監視したい他の仕様は、このアルゴリズムにステップを追加することが奨励されており、変更の結果として発生するイベントの順序が明確になるようにしています。
それぞれのformControlがdocument内にあり、その自動入力フィールド名が「off」である場合、formControlに対してリセットアルゴリズムを実行します。
documentのサスペンドされたタイマーハンドルが空でない場合:
activeTimersをdocumentの関連グローバルオブジェクトのアクティブタイマーのマップに設定します。
それぞれのhandleに対して、documentのサスペンドされたタイマーハンドル内にあり、activeTimers[handle]が存在する場合、そのactiveTimers[handle]をsuspendDurationだけ増加させます。
documentの関連グローバルオブジェクトのナビゲーションAPI、entriesForNavigationAPI、およびreactivatedEntryを指定して再活性化のためにナビゲーションAPIエントリを更新するを実行します。
documentの現在のドキュメント準備状態が「complete」であり、documentのページ表示中フラグがfalseである場合、次の手順を実行します。
documentのページ表示中フラグをtrueに設定します。
documentの表示済みをfalseに設定します。
documentの可視性状態を「visible」に更新します。
documentの関連グローバルオブジェクトに対して、pageshowと名付けたページ遷移イベントを発火するを実行し、trueを渡します。
Document documentのフラグメントへのスクロールを試みるには、次の手順を並列で実行します。
実装依存の時間を待ちます。(これは、パフォーマンスの問題に直面した場合にユーザーエージェントがユーザーエクスペリエンスを最適化することを意図しています。)
documentの関連グローバルオブジェクトに対してグローバルタスクをキューに入れるを実行し、次の手順を実行します。
documentがパーサーを持たないか、そのパーサーがパースを停止しているか、またはユーザーエージェントがユーザーがもはやフラグメントへのスクロールに興味がないと判断した場合、これらの手順を中止します。
documentに対してフラグメントにスクロールするを実行します。
documentの指示された部分が依然としてnullの場合、documentに対してフラグメントへのスクロールを再試行するを実行します。
Document
documentおよび文字列reasonを指定してドキュメントを復旧不能にするには、次の手順を実行します。
detailsを新しい復元されなかった理由の詳細に設定し、その理由をreasonに設定します。
詳細をdocumentのbfcacheブロッキングの詳細に追加します。
documentの復旧可能状態をfalseに設定します。
Document documentを指定してドキュメント状態のために復元されなかった理由を構築するには、次の手順を実行します。
notRestoredReasonsForDocumentを新しい復元されなかった理由に設定します。
notRestoredReasonsForDocumentの理由をdocumentのbfcacheブロッキングの詳細のクローンに設定します。
documentのドキュメントツリー子ナビゲーブルのそれぞれについて、次の手順を実行します。
childDocumentをnavigableのアクティブドキュメントに設定します。
ドキュメント状態のために復元されなかった理由を構築するをchildDocumentに対して実行します。
childDocumentの復元されなかった理由をnotRestoredReasonsForDocumentの子要素に追加します。
documentのノードナビゲーブルのアクティブセッション履歴エントリのドキュメント状態の復元されなかった理由をnotRestoredReasonsForDocumentに設定します。
最上位トラバーサブル topLevelTraversableおよびその子孫を指定して最上位トラバーサブルおよびその子孫のために復元されなかった理由を構築するには、次の手順を実行します。
topLevelTraversableのアクティブドキュメントに対してドキュメント状態のために復元されなかった理由を構築するを実行します。
crossOriginDescendantsを空のリストに設定します。
topLevelTraversableのアクティブドキュメントの子孫ナビゲーブルのそれぞれに対して、次の手順を実行します。
childNavigableのアクティブドキュメントのオリジンが、topLevelTraversableのアクティブドキュメントのオリジンと同一オリジンでない場合、childNavigableをcrossOriginDescendantsに追加します。
crossOriginDescendantsPreventsBfcacheをfalseに設定します。
crossOriginDescendantsのそれぞれに対して、次の手順を実行します。
reasonsForCrossOriginChildをcrossOriginNavigableのアクティブドキュメントのドキュメント状態の復元されなかった理由に設定します。
reasonsForCrossOriginChildの理由が空でない場合、crossOriginDescendantsPreventsBfcacheをtrueに設定します。
reasonsForCrossOriginChildのURLをnullに設定します。
reasonsForCrossOriginChildの理由をnullに設定します。
reasonsForCrossOriginChildの子要素をnullに設定します。
crossOriginDescendantsPreventsBfcacheがtrueの場合、topLevelTraversableのアクティブドキュメントおよび「masked」を指定してドキュメントを復旧不能にするを実行します。
Documentには、表示済みというブール値があり、初期値はfalseです。これは、pagerevealイベントがDocumentの各アクティベーションに対して一度だけ発火されることを保証するために使用されます(最初にレンダリングされたときと、各再アクティベーション時に一度ずつ)。
Document documentを表示するには、次の手順を実行します。
もしdocumentの表示済みがtrueであるなら、終了します。
documentの表示済みをtrueに設定します。
documentに対して、インバウンドクロスドキュメントビュー遷移の解決の結果をtransitionとして設定します。
documentの関連グローバルオブジェクトに対して、イベントを発火するを実行し、イベント名をpagereveal、イベントオブジェクトをPageRevealEvent、そのviewTransitionをtransitionに設定します。
もしtransitionがnullでない場合、次の手順を実行します。
documentに対してスクリプトの実行準備をするを実行します。
ビュー遷移を有効化するをtransitionに対して実行します。
documentに対してスクリプト実行後のクリーンアップを行うを実行します。
ビュー遷移を有効化すると、Promiseが解決または拒否される可能性があるため、実行準備/クリーンアップでラップすることで、次のレンダリングステップの前にそれらのPromiseが処理されることを保証します。
pagerevealは、ページの最新バージョンを表示する最初のレンダリングの更新ステップ中に発火されることが保証されていますが、ユーザーエージェントはそれを発火する前にページのキャッシュフレームを表示することができます。これにより、pagerevealハンドラーの存在がそのようなキャッシュフレームの表示を遅らせるのを防ぎます。
Document documentを指定してフラグメントにスクロールするには、次の手順を実行します。
そうでなければ、もしdocumentの指定された部分がドキュメントの先頭であるなら、次の手順を実行します。
documentのターゲット要素をnullに設定します。
documentに対してドキュメントの最初にスクロールします。[CSSOMVIEW]
終了します。
そうでなければ、次の手順を実行します。
documentの指定された部分をtargetに設定します。
documentのターゲット要素をtargetに設定します。
先祖の詳細を明らかにするアルゴリズムをtargetに対して実行します。
をtargetに対して実行します。
targetを表示範囲にスクロールし、behaviorを"auto"に、blockを"start"に、inlineを"nearest"に設定します。[CSSOMVIEW]
targetに対してフォーカスするステップを実行し、Documentのビューポートをfallback targetとして使用します。
順次フォーカスナビゲーションの開始点をtargetに移動します。
Documentの指定された部分は、そのURLのフラグメントが示す部分です。フラグメントが何も指定していない場合はnullです。ノードにマッピングするフラグメントのセマンティクスは、Documentで使用されるMIMEタイプを定義する仕様によって定義されます(例: フラグメントの処理は、XML
MIMEタイプに関してはRFC7303が責任を負います)。[RFC7303]
また、各Documentにはターゲット要素があり、:target疑似クラスの定義に使用され、上記のアルゴリズムによって更新されます。それは最初はnullです。
HTMLドキュメントであるdocumentの場合、その指定された部分はdocumentとdocumentのURLを指定して指定された部分を選択する結果です。
Document documentとURL
urlを指定して指定された部分を選択するには、次の手順を実行します。
urlのフラグメントをfragmentに設定します。
もしfragmentが空文字列なら、特別な値ドキュメントの先頭を返します。
documentとfragmentを指定して潜在的な指定要素を見つける結果をpotentialIndicatedElementに設定します。
もしpotentialIndicatedElementがnullでないなら、それを返します。
fragmentを指定してパーセントデコードの結果をfragmentBytesに設定します。
fragmentBytesを指定してUTF-8 BOMなしデコードの結果をdecodedFragmentに設定します。
documentとdecodedFragmentを指定して潜在的な指定要素を見つける結果をpotentialIndicatedElementに設定します。
もしpotentialIndicatedElementがnullでないなら、それを返します。
もしdecodedFragmentがtopとASCII大文字小文字を区別しない一致を持つなら、ドキュメントの先頭を返します。
nullを返します。
Document
documentと文字列fragmentを指定して潜在的な指定要素を見つけるには、次の手順を実行します。
もしドキュメントツリー内で、そのルートがdocumentであり、かつそのIDがfragmentと等しい要素が存在するなら、ツリー順で最初のその要素を返します。
もしa要素がドキュメントツリー内で、そのルートがdocumentであり、かつそのname属性の値がfragmentと等しいなら、ツリー順で最初のその要素を返します。
nullを返します。
セッション履歴エントリ entryに永続化された状態を保存するには、次の手順を実行します。
entryのスクロール位置データを、entryのドキュメントの復元可能なスクロール領域全体のスクロール位置を含むように設定します。
必要に応じて、entryの永続化されたユーザー状態を、ユーザーエージェントが保持したい状態(フォームフィールドの値など)を反映するように更新します。
セッション履歴エントリ entryから永続化された状態を復元するには、次の手順を実行します。
もしentryのスクロール復元モードが「auto」であり、かつentryのドキュメントの関連グローバルオブジェクトのナビゲーションAPIの進行中のナビゲーション中に通常のスクロール復元を抑制が偽である場合、entryを指定してスクロール位置データを復元します。
ユーザーエージェントがスクロール位置を復元しないことは、スクロール位置が特定の値(例えば (0,0))に設定されることを意味しません。実際のスクロール位置はナビゲーションの種類やユーザーエージェントのキャッシュ戦略によって異なります。したがって、ウェブアプリケーションは特定のスクロール位置を想定するのではなく、自分が望む位置に設定することが推奨されます。
もし進行中のナビゲーション中に通常のスクロール復元を抑制が真である場合でも、関連するNavigateEventを完了する一環として、またはnavigateEvent.scroll()メソッドの呼び出しによって、後でスクロール位置データが復元されることがあります。
必要に応じて、entryのドキュメントやそのレンダリングの他の側面を更新します。例えば、ユーザーエージェントが以前にentryの永続化されたユーザー状態に記録したフォームフィールドの値などです。
これには、dir属性が設定されているtextarea要素やinput要素の、type属性がテキスト、検索、電話、URL、またはメールのいずれかの状態にある場合、入力コントロールの方向性を含む永続化された状態を更新することが含まれることもあります。
このプロセスの一部としてフォームコントロールの値を復元することは、inputやchangeイベントを発生させることはありませんが、フォーム関連カスタム要素のformStateRestoreCallbackをトリガーすることがあります。
各Documentには、ユーザーによってスクロールされたというブール値があり、最初は偽です。ユーザーがドキュメントをスクロールすると、ユーザーエージェントはそのドキュメントのユーザーによってスクロールされたを真に設定する必要があります。
Document
documentの復元可能なスクロール領域は、documentのビューポートと、documentのスクロール可能な領域のうち、ナビゲーブルコンテナを除いたすべてです。
子ナビゲーブルのスクロール復元は、それらのセッション履歴エントリの状態復元の一部として扱われます。
セッション履歴エントリ entryを指定してスクロール位置データを復元するには、次の手順を実行します。
entryのドキュメントをdocumentとします。
もしdocumentのユーザーによってスクロールされたが真である場合、ユーザーエージェントは終了します。
ユーザーエージェントは、entryのスクロール位置データを使用して、entryのドキュメントの復元可能なスクロール領域のスクロール位置を復元しようとします。ユーザーエージェントは、documentのユーザーによってスクロールされたが真になるまで、定期的にこれを試みることがあります。
これは、スクロール位置データで示された関連コンテンツがネットワークから読み込まれるのに時間がかかる可能性があるため、成功するまで、またはユーザーがスクロールするまで定期的に試みるという形で表現されています。
スクロール復元は、スクロールアンカーリングの影響を受ける可能性があります。[CSSSCROLLANCHORING]
以下のアルゴリズムを使用してドキュメントをロードする際には、タイプ type、コンテンツタイプ contentType、およびナビゲーションパラメータ navigationParamsを指定して、ドキュメントオブジェクトを作成および初期化するための次の手順を使用します。
ドキュメントオブジェクトは、新しいブラウジングコンテキストとドキュメントの作成時にも作成されますが、このアルゴリズムでは初期のabout:blank ドキュメントは決して作成されません。また、ブラウジングコンテキストを持たないドキュメントオブジェクトは、document.implementation.createHTMLDocument()などのさまざまなAPIを介して作成できます。
browsingContextをnavigationParamsのナビゲーブルのアクティブなブラウジングコンテキストに設定します。
ナビゲーション応答に使用するブラウジングコンテキストの取得の結果を基にbrowsingContextを設定します。この取得は、navigationParamsの最終的なサンドボックスフラグセット、navigationParamsのクロスオリジンオープナーポリシー、およびnavigationParamsのCOOP実施結果に基づいて行われます。
これにより、クロスオリジンオープナーポリシーによるブラウジングコンテキストグループの切り替えが発生する可能性があり、その場合、browsingContextはnavigationParamsのナビゲーブルのアクティブなブラウジングコンテキストではなく、新しく作成されたブラウジングコンテキストになります。この場合、作成されたウィンドウ、ドキュメント、およびエージェントは使用されません。作成されたドキュメントのオリジンが不透明であるため、このアルゴリズムの後の段階で、新しいウィンドウと共に使用する新しいエージェントを作成することになります。
permissionsPolicyを、navigationParamsのナビゲーブルのコンテナ、navigationParamsのオリジン、およびnavigationParamsのレスポンスを基にしてレスポンスからの権限ポリシーの作成の結果とします。[PERMISSIONSPOLICY]
レスポンスからの権限ポリシーの作成アルゴリズムでは、指定されたオリジンが使用されます。navigationParamsのナビゲーブルのコンテナドキュメントでdocument.domainが使用された場合でも、documentが作成される前にこれらの手順が実行されるため、渡されたオリジンと同一のオリジンドメインにはなり得ません。このため、権限ポリシーチェックは、同一オリジンチェックを行うよりも制限が厳しくなります。
この動作の具体例は以下をご覧ください。
もしnavigationParamsのリクエストがnullでない場合、creationURLをnavigationParamsのリクエストの現在のURLに設定します。
windowをnullに設定します。
もしbrowsingContextのアクティブなドキュメントの初期about:blankが真であり、かつbrowsingContextのアクティブなドキュメントのオリジンがnavigationParamsのオリジンと同一オリジンドメインである場合、windowをbrowsingContextのアクティブなウィンドウに設定します。
これにより、初期about:blank
ドキュメントと、これから作成される新しいドキュメントの両方が、同じウィンドウオブジェクトを共有することを意味します。
それ以外の場合:
oacHeaderを、navigationParamsのレスポンスのヘッダリストから`Origin-Agent-Cluster`および"item"を指定して構造化フィールド値の取得の結果とします。
requestsOACを、oacHeaderがnullでなく、かつoacHeader[0]がブール値である場合は真、そうでなければ偽とします。
もしnavigationParamsの予約済み環境が非セキュアコンテキストである場合、requestsOACを偽に設定します。
agentを、navigationParamsのオリジン、browsingContextのグループ、およびrequestsOACを基に類似オリジンウィンドウエージェントの取得の結果とします。
realmExecutionContextを、agentを基に新しいJavaScript領域の作成の結果とし、以下のカスタマイズを適用します:
windowをrealmExecutionContextの領域コンポーネントのグローバルオブジェクトに設定します。
topLevelCreationURLをcreationURLに設定します。
topLevelOriginをnavigationParamsのオリジンに設定します。
もしnavigableのコンテナがnullでない場合、次の手順を実行します:
parentEnvironmentをnavigableのコンテナの関連設定オブジェクトに設定します。
topLevelCreationURLをparentEnvironmentの最上位作成URLに設定します。
topLevelOriginをparentEnvironmentの最上位オリジンに設定します。
ウィンドウ環境設定オブジェクトの設定を、creationURL、realmExecutionContext、navigationParamsの予約済み環境、topLevelCreationURL、およびtopLevelOriginで実行します。
loadTimingInfoを、navigationParamsのレスポンスのタイミング情報の開始時間に設定されたナビゲーション開始時間を持つ新しいドキュメント読み込みタイミング情報として設定します。
documentを新しいドキュメントとして設定します。
loading"
windowの関連ドキュメントをdocumentに設定します。
ドキュメントのためのCSP初期化の実行をdocumentに対して実行します。[CSP]
もしnavigationParamsのリクエストがnullでない場合、次の手順を実行します:
もしnavigationParamsのフェッチコントローラーがnullでない場合、次の手順を実行します:
fullTimingInfoを、navigationParamsのフェッチコントローラーから完全なタイミング情報を抽出した結果とします。
navigationParamsのレスポンスのクロスオリジンリダイレクトがあるがtrueの場合、redirectCountを0にします。それ以外の場合は、navigationParamsのリクエストのリダイレクトカウントにします。
documentのナビゲーションタイミングエントリを作成します。fullTimingInfo、redirectCount、navigationTimingType、navigationParamsのレスポンスのサービスワーカータイミング情報、およびnavigationParamsのレスポンスのボディ情報に基づいて。
documentのナビゲーションタイミングエントリを作成します。navigationParamsのレスポンスのタイミング情報、redirectCount、navigationParamsのナビゲーションタイミングタイプ、およびnavigationParamsのレスポンスのサービスワーカータイミング情報に基づいて。
もしnavigationParamsのレスポンスに`リフレッシュ`ヘッダーが含まれている場合、次の手順を実行します:
valueを、ヘッダーの値の等形デコードの結果とします。
共有宣言的リフレッシュ手順をdocumentとvalueを指定して実行します。
複数の`リフレッシュ`ヘッダーの処理方法については、現在仕様がありません。これはissue #2900として追跡されています。
もしnavigationParamsの早期ヒントのコミットがnullでない場合、navigationParamsの早期ヒントのコミットをdocumentに対して呼び出します。
リンクヘッダーの処理を、document、navigationParamsのレスポンス、および"pre-media"を指定して実行します。
documentを返します。
この例では、子ドキュメントはPaymentRequestを使用することが許可されていませんが、同じオリジンドメインであるにもかかわらず、子ドキュメントがそれを使用しようとする時点で、親ドキュメントのみがdocument.domainを設定しており、子ドキュメントは設定していません。
<!-- https://foo.example.com/a.html -->
<!doctype html>
< script >
document. domain = 'example.com' ;
</ script >
< iframe src = b.html ></ iframe >
<!-- https://bar.example.com/b.html -->
<!doctype html>
< script >
document. domain = 'example.com' ; // ドキュメントが初期化された後にこれが発生します
new PaymentRequest( …); // 使用が許可されていません
</ script >
この例では、子ドキュメントがPaymentRequestを使用することが許可されていますが、子ドキュメントがそれを使用しようとする時点では、どのドキュメントもdocument.domainを設定しておらず、そのため、同じオリジンドメインが通常の同じオリジンチェックに戻ります。
<!-- https://example.com/a.html -->
<!doctype html>
< iframe src = b.html ></ iframe >
<!-- 子ドキュメントが初期化され、以下のスクリプトが実行される前に -->
< script >
document. domain = 'example.com' ;
</ script >
<!-- https://example.com/b.html -->
<!doctype html>
< script >
new PaymentRequest( …); // 使用が許可されています
</ script >
html/head/bodyで構築するには、与えられたDocumentに対して、以下の手順を実行します。
htmlを要素を作成することによって生成します。与えられたdocument、html、およびHTML名前空間を使用します。
headを要素を作成することによって生成します。与えられたdocument、head、およびHTML名前空間を使用します。
bodyを要素を作成することによって生成します。与えられたdocument、body、およびHTML名前空間を使用します。
htmlをdocumentに追加します。
headをhtmlに追加します。
bodyをhtmlに追加します。
HTML文書を読み込むには、ナビゲーションパラメータ navigationParamsが与えられた場合、次の手順を実行します。
「html」、「text/html」、およびnavigationParamsを指定して、Documentオブジェクトを作成および初期化する結果として、documentを取得します。
もしdocumentのURLがabout:blankである場合、「html/head/body」で埋めるをdocumentに対して実行します。
この特別なケースでは、非初期のabout:blank Documentでも、その要素ノードが同期的に与えられることが必要です。言い換えれば、代わりに「それ以外」の分岐に進んで空のバイトシーケンスをHTMLパーサーに渡して、非同期的にdocumentを埋めるのは互換性がありません。
それ以外の場合、HTMLパーサーを作成し、documentに関連付けます。 フェッチ中にネットワーキングタスクソースがタスクキューに配置するタスクは、取得されたバイトをパーサーの入力バイトストリームに埋め、それがHTMLパーサーにストリームの適切な処理を実行させる必要があります。
フェッチ中にネットワーキングタスクソースがタスクキューに配置する最初のタスクは、タスクがHTMLパーサーで処理された後、document、navigationParamsのレスポンス、および「media」を与えられて、リンクヘッダーを処理する必要があります。
スクリプトの実行が発生する前に、ユーザーエージェントはdocumentに対して新しく作成されたドキュメントのためにスクリプトが実行される可能性があるを待つ必要があります。
入力バイトストリームは、トークナイザで使用するためにバイトを文字に変換します。このプロセスは部分的に、リソースの実際のContent-Typeメタデータに見つかった文字エンコーディング情報に依存します。計算されたタイプはこの目的には使用されません。
これ以上バイトが利用できない場合、ユーザーエージェントはdocumentの関連するグローバルオブジェクトを指定してグローバルタスクをキューに追加し、パーサーに暗黙のEOF文字を処理させ、最終的にloadイベントが発生するようにします。
documentを返します。
XMLファイルをインラインで表示する場合、ナビゲーションパラメータ
navigationParamsと文字列typeが与えられている場合、ユーザーエージェントは、XML、Namespaces in
XML、XML Media
Types、DOM、およびその他の関連仕様で定義された要件に従い、"xml"、type、およびnavigationParamsを指定してDocumentオブジェクトを作成および初期化する
documentを作成し、それを返す必要があります。また、対応するXMLパーサーも作成する必要があります。[XML] [XMLNS] [RFC7303] [DOM]
執筆時点では、XML仕様コミュニティは、XMLとDOMの相互作用についてまだ正式に仕様化していませんでした。
タスクを実行中に、ネットワーキングタスクソースがタスクキューに配置する最初のタスクは、リンクヘッダーを処理する必要があります。document、navigationParamsのレスポンス、および"media"が与えられた後、このタスクはXMLパーサーによって処理されます。
実際のHTTPヘッダーやその他のメタデータ(この仕様で与えられたアルゴリズムによって変更されたり、暗示されたりしたヘッダーではない)を使用して、上記の仕様で定められたルールに従って文字エンコーディングを決定する必要があります。文字エンコーディングが確立されると、ドキュメントの文字エンコーディングをその文字エンコーディングに設定する必要があります。
スクリプトの実行が発生する前に、ユーザーエージェントは、新しく作成されたDocumentに対してスクリプトが実行される可能性があるを待つ必要があります。
解析が完了すると、ユーザーエージェントはdocumentのWebDriver BiDiの読み込み中のナビゲーションIDをnullに設定する必要があります。
HTML文書の場合、これは読み込みイベントが発生した後、解析が完了したときにリセットされます。
解析プロセスからのエラーメッセージ(例:XML名前空間の整形式エラーなど)は、Documentを変更することでインラインで報告される場合があります。
テキスト文書を読み込むには、ナビゲーションパラメータ navigationParamsと文字列typeが与えられた場合、次の手順を実行します。
「html」、type、およびnavigationParamsを指定してDocumentオブジェクトを作成および初期化する結果として、documentを取得します。
documentのパーサーはモードを変更できないフラグをtrueに設定します。
documentのモードを「no-quirks」に設定します。
HTMLパーサーを作成し、documentに関連付けます。トークナイザがタグ名「pre」を持つ開始タグトークンを発行し、それに続く単一のU+000A LINE FEED (LF) 文字を発行したかのように振る舞い、HTMLパーサーのトークナイザをPLAINTEXT状態に切り替えます。フェッチ中にネットワーキングタスクソースがタスクキューに配置するタスクは、取得されたバイトを入力バイトストリームに埋め、それがHTMLパーサーにストリームの適切な処理を実行させる必要があります。
documentの文字エンコーディングは、解析中にドキュメントをデコードするために使用された文字エンコーディングに設定される必要があります。
フェッチ中にネットワーキングタスクソースがタスクキューに配置する最初のタスクは、タスクがHTMLパーサーで処理された後、document、navigationParamsのレスポンス、および「media」を与えられて、リンクヘッダーを処理する必要があります。
スクリプトの実行が発生する前に、ユーザーエージェントはdocumentに対して新しく作成されたドキュメントのためにスクリプトが実行される可能性があるを待つ必要があります。
これ以上バイトが利用できない場合、ユーザーエージェントはdocumentの関連するグローバルオブジェクトを指定してグローバルタスクをキューに追加し、パーサーに暗黙のEOF文字を処理させ、最終的にloadイベントが発生するようにします。
ユーザーエージェントは、documentのhead要素にコンテンツを追加することができます。例えば、スタイルシートへのリンク、スクリプトの提供、ドキュメントにタイトルを与えるなどです。
特に、ユーザーエージェントがRFC
3676のFormat=Flowed機能をサポートしている場合、テキストが正しく折り返されるようにし、引用機能を処理するために追加のスタイリングを適用する必要があります。これは例えば、CSS拡張を使用して行うことができます。
documentを返します。
プレーンテキスト文書のバイトを実際の文字に変換する方法、およびテキストをユーザーに実際にレンダリングするルールは、リソースの計算されたMIMEタイプ(すなわち、type)の仕様で定義されています。
multipart/x-mixed-replace文書の読み込みmultipart/x-mixed-replace文書を読み込むには、ナビゲーションパラメータ
navigationParams、ソーススナップショットパラメータ
sourceSnapshotParams、およびオリジン initiatorOriginが与えられた場合、次の手順を実行します。
firstPartNavigationParamsをnavigationParamsのコピーとして作成します。
firstPartNavigationParamsのレスポンスを、navigationParamsのレスポンスの本文のマルチパートストリームを表す新しいレスポンスに設定します。
documentを取得するために、firstPartNavigationParams、sourceSnapshotParams、およびinitiatorOriginを指定して文書を読み込む結果を得ます。
navigationParamsのレスポンスから取得された追加の本文パートごとに、ユーザーエージェントはdocumentのノードナビゲーブルを、documentを使用して、navigationParamsのリクエストのURLにナビゲートし、レスポンスをnavigationParamsのレスポンスに設定し、履歴処理を"置換"に設定します。
documentを返します。
これらの本文パートを完全な独立したリソースとして処理するアルゴリズムの目的のために、ユーザーエージェントは、本文パートに続く境界に到達するたびに、これ以上そのリソースのバイトが存在しないかのように振る舞う必要があります。
したがって、loadイベント(およびunloadイベントも含む)は、読み込まれた各本文パートに対して発生します。
メディア文書を読み込むには、navigationParamsと文字列typeが与えられた場合、次の手順を実行します。
「html」、type、およびnavigationParamsを指定してDocumentオブジェクトを作成および初期化する結果として、documentを取得します。
documentのモードを「no-quirks」に設定します。
「html/head/body」で埋めるをdocumentに対して実行します。
以下に記述されているように、メディア用の要素ホスト要素を作成し、それをbody要素に追加します。
以下に記述されているように、メディアのアドレスをホスト要素の適切な属性に設定します。
ユーザーエージェントは、documentのhead要素にコンテンツを追加したり、ホスト要素に属性を追加したりすることができます。例えば、スタイルシートへのリンク、スクリプトの提供、ドキュメントにタイトルを与えたり、メディアを自動再生するようにしたりすることができます。
document、navigationParamsのレスポンス、および"media"を与えられて、リンクヘッダーを処理する必要があります。
ユーザーエージェントがdocumentの解析を停止したかのように振る舞います。
documentを返します。
メディアのために作成する要素ホスト要素は、下記の表の第1列にメディアが記載されている行の第2列に示されている要素です。設定すべき適切な属性は、その行の第3列に示されている属性です。
| メディアの種類 | メディアのための要素 | 適切な属性 |
|---|---|---|
| 画像 | img
| src
|
| 動画 | video
| src
|
| 音声 | audio
| src
|
スクリプトの実行が発生する前に、ユーザーエージェントは、Documentに対して新しく作成されたドキュメントのためにスクリプトが実行される可能性があるを待つ必要があります。
ユーザーエージェントが、ユーザーエージェントページまたはPDFビューアをインラインで表示するための文書を作成する場合、ナビゲーブル navigable、ナビゲーションID navigationId、およびNavigationTimingType
navTimingTypeが与えられた場合、ユーザーエージェントは以下の手順を実行します。
originを新しい不透明なオリジンとして設定します。
coopを新しいクロスオリジンオープナーポリシーとして設定します。
coopEnforcementResultを新しいクロスオリジンオープナーポリシーの施行結果として、次のプロパティを設定して作成します。
navigationParamsを新しいナビゲーションパラメータとして、次のプロパティを設定して作成します。
documentを「html」、「text/html」、およびnavigationParamsを指定してDocumentオブジェクトを作成および初期化する結果として取得します。
通常のDocumentレンダリングルールを使用せずにレンダリングされるカスタムレンダリングにdocumentを関連付けるか、またはdocumentを変更して、ユーザーエージェントがレンダリングしたいコンテンツを表すようにします。
documentを返します。
結果として得られるDocumentのオリジンが不透明であることを保証し、結果として得られるDocumentがDOMにアクセスできるスクリプトを実行できないため、このDocumentの存在やプロパティはウェブ開発者のコードに観察されることはありません。つまり、上記のほとんどの値、例えばtext/html タイプは重要ではありません。同様に、navigationParamsのほとんどの項目は、Document作成アルゴリズムが混乱しないようにすることを除いて、観察可能な効果はありません。そのため、デフォルト値に設定されています。
ページが設定されたら、ユーザーエージェントは解析を停止したかのように振る舞う必要があります。
Documentには、最初はnullである完全に読み込まれた時刻(時刻またはnull)が設定されています。
Documentは、その完全に読み込まれた時刻がnullでない場合、完全に読み込まれたと見なされます。
Document documentを完全に読み込み完了するには、次の手順を実行します。
documentのブラウジングコンテキストがnullでないことを確認します。
documentの完全に読み込まれた時刻を現在時刻に設定します。
containerをdocumentのノードナビゲーブルのコンテナとして設定します。
これは、documentが初期のabout:blank Documentである場合、つまりframeまたはiframeにおいて、このアルゴリズムを呼び出すブラウジングコンテキストの作成の時点でコンテナの関係がまだ確立されていないため、nullになります。(これは、新しい子ナビゲーブルの作成の後続のステップで発生します。)
この結果として、以下の手順は何もしません。つまり、そのような場合にコンテナ要素に対して非同期のloadイベントは発生しません。代わりに、iframe属性の処理時に、特別な初期挿入ケースで同期的なloadイベントが発生します。
もしcontainerがiframe要素である場合、containerを指定して要素タスクをキューに追加するをDOM操作タスクソースに対して実行し、containerを指定してiframe読み込みイベント手順を実行します。
それ以外の場合、containerがnullでない場合は、containerを与えて、DOM操作タスクソース上で要素タスクをキューに入れ、containerでloadイベントを発火させます。
Documentには、初期状態がtrueである救済可能な状態と、初期状態がfalseであるページ表示中フラグがあります。このページ表示中フラグは、スクリプトがpageshowおよびpagehideイベントを一貫した方法で受け取ることを保証するために使用されます(例:
連続して2つのpagehideイベントを受け取らない、またはその逆)。
Documentには、DOMHighResTimeStamp
一時停止時間があり、初期値は0です。
Documentには、最初は空である一時停止されたタイマーハンドルのリストがあります。
イベントループには、最初は0である終了ネスティングレベルカウンターがあります。
Documentオブジェクトには、以下のアルゴリズムが実行されている間に特定の操作を無視するために使用されるアンロードカウンターがあります。カウンターの初期値はゼロに設定されている必要があります。
Document oldDocumentをアンロードするには、オプションでDocument
newDocumentを指定して、以下の手順を実行します。
確認: これはoldDocumentの関連するエージェントのイベントループにキューされたタスクの一部として実行されます。
unloadTimingInfoを新しい文書アンロードタイミング情報として設定します。
newDocumentが指定されていない場合、unloadTimingInfoをnullに設定します。
この場合、oldDocumentのアンロードにかかった時間について新しい文書に通知する必要はありません。
それ以外の場合、newDocumentのイベントループがoldDocumentのイベントループと異なる場合、ユーザーエージェントはoldDocumentをアンロードすることができます。並行してこの場合、ユーザーエージェントはunloadTimingInfoをnullに設定する必要があります。
この場合、newDocumentの読み込みにoldDocumentのアンロードにかかった時間が影響しないため、そのタイミング情報を伝える意味はありません。
ユーザーエージェントがoldDocumentをセッション履歴エントリで後で履歴の移動に使用されるように保持するつもりであれば、intendToKeepInBfcacheをtrueに設定します。
これは、oldDocumentが救済可能でない場合、またはユーザーエージェントが同じ方法で保持するつもりのないoldDocumentの子孫が存在する場合(救済可能性の欠如などを含む)、falseに設定する必要があります。
eventLoopをoldDocumentの関連するエージェントのイベントループとして設定します。
eventLoopの終了ネスティングレベルを1増やします。
oldDocumentのアンロードカウンターを1増やします。
もしintendToKeepInBfcacheがfalseであれば、oldDocumentの救済可能状態をfalseに設定します。
もしoldDocumentのページ表示中がtrueであれば:
oldDocumentのページ表示中をfalseに設定します。
oldDocumentの救済可能状態でoldDocumentの関連するグローバルオブジェクトにページ遷移イベントを発生させます。イベント名はpagehideです。
oldDocumentの可視性状態を"hidden"に更新します。
もしunloadTimingInfoがnullでない場合、unloadTimingInfoのアンロードイベント開始時間をnewDocumentの関連するグローバルオブジェクトに対して現在の高解像度時間で設定し、oldDocumentの関連する設定オブジェクトのクロスオリジン分離機能に応じて粗くしたものに設定します。
もしoldDocumentの回復可能状態がfalseの場合、legacy target override
flagを設定して、oldDocumentの関連グローバルオブジェクトでunloadイベントを発火させます。
もしunloadTimingInfoがnullでない場合、unloadTimingInfoのアンロードイベント終了時間をnewDocumentの関連するグローバルオブジェクトに対して現在の高解像度時間で設定し、oldDocumentの関連する設定オブジェクトのクロスオリジン分離機能に応じて粗くしたものに設定します。
eventLoopの終了ネスティングレベルを1減らします。
oldDocumentの一時停止時間をdocumentの関連するグローバルオブジェクトに対して現在の高解像度時間に設定します。
oldDocumentの一時停止されたタイマーハンドルをキーの取得で得たアクティブタイマーのマップの結果に設定します。
oldDocumentのユーザーによってスクロールされたをfalseに設定します。
この仕様とその他の適用可能な仕様によって定義されたoldDocumentに対する文書アンロードのクリーンアップ手順を実行します。
もしoldDocumentのナビゲーブルノードがトップレベルトラバーサブルであれば、oldDocumentのナビゲーブルノードを指定してトップレベルトラバーサブルとその子孫の復元されなかった理由を構築します。
oldDocumentのアンロードカウンターを1減らします。
もしnewDocumentが指定され、newDocumentのクロスオリジンリダイレクトによって作成されたがfalseであり、newDocumentのオリジンがoldDocumentのオリジンと同じであれば、newDocumentの前の文書アンロードタイミングをunloadTimingInfoに設定します。
document、オプションでnewDocumentをnull既定値として指定し、オプションでafterAllUnloadsおよびfirePageSwapStepsの手順を指定して、文書とその子孫をアンロードするには、以下の手順を実行します。
確認: これはdocumentのナビゲーブルノードのトラバーサブルナビゲーブルのセッション履歴移動キュー内で実行されています。
childNavigablesをdocumentの子ナビゲーブルとして設定します。
numberUnloadedを0に設定します。
childNavigableのどの順序で?のchildNavigableごとに反復して、childNavigableのアクティブウィンドウにグローバルタスクをキューに追加して、以下の手順を実行します。
incrementUnloadedをnumberUnloadedを増やすアルゴリズムステップとして設定します。
childNavigableのアクティブ文書、null、およびincrementUnloadedを指定して文書とその子孫をアンロードします。
numberUnloadedがchildNavigableのサイズと等しくなるまで待ちます。
documentの関連するグローバルオブジェクトを指定してグローバルタスクをキューに追加して、以下の手順を実行します。
もしfirePageSwapStepsが指定されていれば、firePageSwapStepsを実行します。
newDocumentがnullでない場合にnewDocumentを渡してdocumentをアンロードします。
もしafterAllUnloadsが指定されていれば、それを実行します。
この仕様は、以下の文書アンロードのクリーンアップ手順を定義しています。他の仕様はさらに定義することができます。Document documentを指定して:
windowをdocumentの関連するグローバルオブジェクトとして設定します。
windowを関連するグローバルオブジェクトとして持つWebSocketオブジェクトwebSocketごとに、webSocketを消失させます。
もしこれがWebSocketオブジェクトに影響を与えた場合、documentを指定して"websocket"を与えて文書を救済不可能にします。
windowを関連するグローバルオブジェクトとして持つWebTransportオブジェクトtransportごとに、transportを指定してコンテキストのクリーンアップ手順を実行します。
もしdocumentの救済可能状態がfalseであれば:
windowを関連するグローバルオブジェクトとして持つEventSourceオブジェクトeventSourceごとに、eventSourceを指定して強制的に閉じます。
windowのアクティブタイマーのマップを指定してクリアします。
仕様の著者がこのフックを使用する代わりに、直接仕様に呼び出しを追加するプルリクエストを送信した方が、仕様間の呼び出し順序を明確にするためにより良いでしょう。この文書を書いている時点で、以下の仕様は未定義の順序で実行される文書アンロードのクリーンアップ手順を持っていることが知られています:Fullscreen
API、Web NFC、WebDriver BiDi、Compute Pressure、File
API、Media Capture and Streams、Picture-in-Picture、Screen
Orientation、Service Workers、WebLocks API、WebAudio
API、WebRTC。[FULLSCREEN] [WEBNFC]
[WEBDRIVERBIDI] [COMPUTEPRESSURE] [FILEAPI] [MEDIASTREAM] [PICTUREINPICTURE] [SCREENORIENTATION]
[SW] [WEBLOCKS] [WEBAUDIO] [WEBRTC]
Issue #8906では、これらの手順の順序を明確にする作業を追跡しています。
ドキュメントdocumentを破棄するには:
文書を中止します documentを。
documentの救済可能な状態をfalseに設定します。
portsを、documentを関連するグローバルオブジェクトとして持つMessagePortのリストとして設定します。
ports内の各portについて、ポートを切り離します。
この仕様とその他の適用可能な仕様によって定義されたdocumentの文書アンロードのクリーンアップ手順を実行します。
documentのブラウジングコンテキストをnullに設定します。
documentのナビゲーブルノードのアクティブなセッション履歴エントリの文書状態の文書をnullに設定します。
documentを各WorkerGlobalScopeオブジェクトの所有者セットから削除します。
documentのワークレットグローバルスコープ内の各workletGlobalScopeについて、ワークレットグローバルスコープを終了します。
破棄後でも、文書オブジェクト自体は、子ナビゲーブルを破棄する場合にスクリプトからアクセス可能なままであるかもしれません。
文書
documentと、オプションの手順セットafterAllDestructionを指定して、文書とその子孫を破棄するには、以下の手順を並行して実行します:
もしdocumentが完全にアクティブでない場合:
documentを指定して、"masked"で文書を救済不可能にします。
もしdocumentのナビゲーブルノードがトップレベルトラバーサブルであれば、documentのナビゲーブルノードを指定して、トップレベルトラバーサブルとその子孫が復元されなかった理由を構築します。
childNavigablesをdocumentの子ナビゲーブルとして設定します。
numberDestroyedを0に設定します。
childNavigableのどの順序で?のchildNavigableごとに、childNavigableのアクティブウィンドウを指定して、グローバルタスクをキューに追加して、以下の手順を実行します:
incrementDestroyedをnumberDestroyedを増やすアルゴリズムステップとして設定します。
childNavigableのアクティブ文書とincrementDestroyedを指定して、文書とその子孫を破棄します。
numberDestroyedがchildNavigableのサイズと等しくなるまで待ちます。
documentの関連するグローバルオブジェクトを指定して、グローバルタスクをキューに追加して、以下の手順を実行します。
もしafterAllDestructionが指定されていれば、それを実行します。
中止するには ドキュメント
document:
確認: これは、タスクの一部として実行されています documentの関連するエージェントのイベントループにキューイングされたものです。
フェッチ
アルゴリズムをキャンセルします
documentの文脈内で、それらのためにタスクをキューイングし、さらに
受信したデータを破棄します。これにより、フェッチ
アルゴリズムがキャンセルされたり、キューイングされたタスクやネットワークデータが破棄された場合、ドキュメントを救済不能にする
documentと
"フェッチ"が適用されます。
もしdocumentのWebDriver BiDiのロード中のナビゲーションIDがnullでない場合:
WebDriver BiDiナビゲーションが中止されましたを呼び出し、
documentのブラウジングコンテキストと新しいWebDriver BiDiナビゲーションステータスの
IDが
documentのWebDriver
BiDiのロード中のナビゲーションID、
ステータスが"キャンセルされました"であること、
そしてURLがdocumentのURLであること。
documentのWebDriver BiDiのロード中のナビゲーションIDをnullに設定します。
もしdocumentがアクティブなパーサーを持っている場合:
documentのアクティブなパーサーが中止されたことを trueに設定します。
documentの救済可能を falseに設定します。
ドキュメントを救済不能にします
documentと
"パーサーが中止された"が適用されます。
ドキュメントとその子孫を中止するには
ドキュメント
document:
確認: これは、タスクの一部として実行されています documentの関連するエージェントのイベントループにキューイングされたものです。
descendantNavigablesをdocumentの子孫のナビゲイブルとして設定します。
それぞれ descendantNavigableの descendantNavigablesのどの順序で?、グローバルタスクをキューイングします、ナビゲーションおよびトラバーサルタスクソースが descendantNavigableのアクティブなウィンドウに対して行う 次のステップ:
中止します descendantNavigableのアクティブなドキュメント。
もしdescendantNavigableのアクティブな ドキュメントの救済可能がfalseであるなら、 documentの救済可能を falseに設定します。
中止します document。
を停止します ナビゲイブル navigable:
documentをnavigableのアクティブな ドキュメントとして設定します。
もしdocumentのアンロードカウンターが0であり、navigableの 進行中の ナビゲーションが ナビゲーションIDである場合、 進行中の ナビゲーションを設定します navigableのためにnullにします。
これにより、navigableの進行中のナビゲーションが中止されます、なぜならナビゲーションの特定のポイントで、進行中のナビゲーションの 変更は、さらなる作業の中止を引き起こすからです。
ドキュメントとその 子孫を中止します document。
彼らのユーザーインターフェースを通じて、ユーザーエージェントもトラバーサルの停止を許可します、つまり、進行中のナビゲーションが
"トラバーサル"である場合です。
上記のアルゴリズムはこれを考慮していません。(一方、
ユーザーエージェントはwindow.stop()
が
トラバーサルを停止することを許可していません、
そのため上記のアルゴリズムはその呼び出しに対して正しいものです。)参照issue
#6905。
X-Frame-Options`
ヘッダーすべての現行エンジンでサポートされています。
`X-Frame-Options` HTTPレスポンス
ヘッダーは、
ドキュメントがDocument内で読み込まれるかどうか、
またどのように読み込まれるかを制御するためのレガシーな方法です。
これは、同じ状況に対してより細かい制御を提供するCSPディレクティブのframe-ancestors
により廃止されました。もともとはHTTP Header Field X-Frame-Optionsで定義されていましたが、
ここでの定義と処理モデルがその文書を上書きします。
[CSP] [RFC7034]
特に、HTTP Header Field X-Frame-Optionsは、`ALLOW-FROM`
ヘッダーのバリアントを指定しましたが、これは実装しないことになっています。
以下の処理モデルによると、CSPframe-ancestors
ディレクティブと
`X-Frame-Options`
ヘッダーが同じレスポンス内で使用された場合、
`X-Frame-Options`
は無視されます。
Web開発者および適合チェッカーのために、その値ABNFは次の通りです:
X-Frame-Options = "DENY" / "SAMEORIGIN"
ナビゲーションレスポンスの`X-Frame-Options`準拠性をチェックするには、
レスポンス
response、ナビゲイブル
navigable、CSPリスト
cspList、およびオリジン
destinationOriginを与えます:
もしnavigableが子ナビゲイブルでない場合、trueを返します。
それぞれ cspListの policyについて:
もしpolicyのディレクティブセットが
frame-ancestors
ディレクティブを含む場合、trueを返します。
rawXFrameOptionsを取得し、デコードし、分割した結果として
`X-Frame-Options`
をresponseのヘッダーリストから取得します。
xFrameOptionsを新しいセットとして設定します。
それぞれのrawXFrameOptionsのvalueについて、 追加 valueを ASCII小文字に変換して、 xFrameOptionsに追加します。
もしxFrameOptionsのサイズが
1を超え、
xFrameOptionsが次のいずれかを含む場合、falseを返します:
"deny", "allowall", または "sameorigin"。
ここでの意図は、`X-Frame-Options`
の有効な処理を試みていたが、混乱しているように見える試みをブロックすることです。
これは、レガシーな`ALLOWALL`値の処理モデルに与える唯一の影響です。
もしxFrameOptionsのサイズが 1を超える場合、trueを返します。
これは、複数の無効な値が含まれていることを意味し、その場合、ヘッダーが完全に省略されたかのように処理されます。
もしxFrameOptions[0]が"deny"である場合、falseを返します。
もしxFrameOptions[0]が"sameorigin"である場合:
containerDocumentをnavigableのコンテナドキュメントとして設定します。
次の間 containerDocumentがnullでない間:
もしcontainerDocumentのオリジン がdestinationOriginと同一オリジン でない場合、falseを返します。
containerDocumentをcontainerDocumentのコンテナドキュメントに設定します。
trueを返します。
ここまで到達した場合、単独の無効な値(レガシーな`ALLOWALL`または`ALLOW-FROM`形式の可能性があるもの)が含まれていることになります。これらは、ヘッダーが完全に省略されたかのように処理されます。
次の表は、ヘッダーのさまざまな値の処理を示しており、不適合なものも含まれます:
`X-Frame-Options`
| 有効 | 結果 |
|---|---|---|
`DENY`
| ✅ | 埋め込み不可 |
`SAMEORIGIN`
| ✅ | 同一オリジンの埋め込み許可 |
`INVALID`
| ❌ | 埋め込み許可 |
`ALLOWALL`
| ❌ | 埋め込み許可 |
`ALLOW-FROM=https://example.com/`
| ❌ | 埋め込み許可(どこからでも) |
次の表は、複数の値に関わる非準拠なケースがどのように処理されるかを示しています:
`X-Frame-Options`
| 結果 |
|---|---|
`SAMEORIGIN, SAMEORIGIN`
| 同一オリジンの埋め込み許可 |
`SAMEORIGIN, DENY`
| 埋め込み不可 |
`SAMEORIGIN,`
| 埋め込み不可 |
`SAMEORIGIN, ALLOWALL`
| 埋め込み不可 |
`SAMEORIGIN, INVALID`
| 埋め込み不可 |
`ALLOWALL, INVALID`
| 埋め込み不可 |
`ALLOWALL,`
| 埋め込み不可 |
`INVALID, INVALID`
| 埋め込み許可 |
値がコンマ区切りの単一ヘッダーで配信されるか、複数のヘッダーで配信されるかにかかわらず、結果は同じです。
リフレッシュ` ヘッダー`リフレッシュ` HTTPレスポンスヘッダーは、
meta要素の
http-equiv
属性がリフレッシュ状態にある場合と同等です。
このヘッダーは同じ値を取り、大部分で同じように動作します。
その処理モデルの詳細はドキュメントオブジェクトの作成と初期化に記載されています。
ブラウザユーザーエージェントは、ナビゲート、リロード、 および読み込み停止を行う能力を提供する必要があります。 これらは、ユーザーの最上位のトラバーサブルを 最上位のトラバーサブルセットに含むものです。
例えば、ロケーションバーやリロード/停止ボタンのUIを介して。
ブラウザユーザーエージェントは、任意の最上位のトラバーサブルを デルタでトラバースする能力を提供する必要があります。 これらはユーザーの最上位のトラバーサブルセットに含まれるものです。
例えば、戻るボタンと進むボタンを介して、長押ししてデルタを変更する能力も含まれるかもしれません。
このようなユーザーエージェントは、デルタが1を超えるトラバースを許可することを提案します。これにより、セッション履歴に無意味なエントリーを詰め込むことでユーザーを「閉じ込める」ページを回避できます。(例えば、繰り返しhistory.pushState()
を呼び出したり、フラグメントナビゲーションを利用したりすることによって。)
一部のユーザーエージェントには、単一の「戻る」または「進む」ボタンの押下を、特定の悪用を克服するためにより大きなデルタに変換するヒューリスティックがあります。これらのヒューリスティックをissue #7832で仕様化することを検討しています。
ブラウザユーザーエージェントは、ユーザーに与えられたか、ユーザーエージェントによって決定された初期URLに基づいて、新しい最上位のトラバーサブルを作成する能力を提供する必要があります。
例えば、「新しいタブ」または「新しいウィンドウ」ボタンを介して。
ブラウザユーザーエージェントは、任意の最上位のトラバーサブルを 任意に閉じる能力を提供する必要があります。 これらはユーザーの最上位のトラバーサブルセットに含まれるものです。
例えば、「タブを閉じる」ボタンをクリックすることで。
ブラウザユーザーエージェントは、ナビゲイブル(最上位のトラバーサブルだけでなく)を 明示的にナビゲート、リロード、または読み込み停止させる方法を提供するかもしれません。
例えば、コンテキストメニューを介して。
ブラウザユーザーエージェントは、ユーザーに最上位のトラバーサブルを破棄する能力を提供するかもしれません。
例えば、1つ以上の最上位のトラバーサブルを含むウィンドウを強制的に閉じることで。
ユーザーがナビゲイブルのリロードを要求したとき、そのアクティブなセッション履歴エントリーのドキュメント状態のリソースがPOSTリソースである場合、ユーザーエージェントは操作を確認するようユーザーにプロンプトを表示する必要があります。そうしないと、トランザクション(例:購入やデータベースの変更)が繰り返される可能性があるためです。
ユーザーがナビゲイブルのリロードを要求したとき、ユーザーエージェントはリロード時にキャッシュを無視するメカニズムを提供するかもしれません。
上記のメカニズムによって開始されたすべてのナビゲート呼び出しは、ユーザー関与引数を"ブラウザUI"に設定する必要があります。
上記のメカニズムによって開始されたすべてのリロード呼び出しは、ユーザー関与引数を"ブラウザUI"に設定する必要があります。
上記のメカニズムによって開始されたすべての履歴をデルタでトラバースする呼び出しは、ソースドキュメント引数に値を渡してはいけません。
上記の推奨事項やこの仕様書のデータ構造は、ユーザーエージェントがセッション履歴をユーザーにどのように表現するかに制限を設けることを意図したものではありません。
例えば、最上位のトラバーサブルのセッション履歴エントリーはリストとして保存・管理されており、ユーザーエージェントにはデルタでそのリストをトラバースするインターフェースを提供することが推奨されますが、革新的なユーザーエージェントは、代わりにまたは追加でツリー状のビューを提供し、各ページが複数の「進む」ページを持ち、ユーザーが選択できるようにすることができます。
同様に、すべての子孫ナビゲイブルのセッション履歴はトラバーサブルナビゲイブルに保存されますが、ユーザーエージェントはセッション履歴をより詳細に個別のナビゲイブルビューとして表示することもできます。
ブラウザユーザーエージェントは、最上位のブラウジングコンテキストのポップアップかどうかのブール値を次の目的で使用する場合があります:
対応する最上位のトラバーサブルに対して最小限のウェブブラウザーのユーザーインターフェースを提供するかどうかを決定する。
オプションの手順を実行するためにブラウジングコンテキストの設定機能をセットアップする。
どちらの場合でも、ユーザーエージェントはユーザーの好みを組み込んだり、ポップアップルートを進むかどうかを選択する選択肢を提示するかもしれません。
このようなポップアップに対して最小限のユーザーインターフェースを提供するユーザーエージェントは、ブラウザーのロケーションバーを隠さないことが推奨されます。
さまざまなメカニズムにより、著者が提供する実行可能なコードがドキュメントのコンテキストで実行されることがあります。これらのメカニズムには、次のものが含まれますが、それに限定されるわけではありません:
script要素の処理。
javascript: URLへのナビゲーション。
addEventListener()で登録された、またはイベントハンドラーコンテンツ属性やイベントハンドラーIDL属性、その他の方法で明示的に登録されたイベントハンドラー。
JavaScriptは、エージェントの概念を定義しています。このセクションでは、その言語レベルの概念をウェブプラットフォームにマッピングします。
概念的には、エージェントの概念は、JavaScriptコードが実行されるアーキテクチャに依存しない理想化された「スレッド」です。このようなコードは複数のグローバル/レルムを含む可能性があり、これらは同期的に相互にアクセスできるため、単一の実行スレッドで実行される必要があります。
同じエージェントを持つ二つのWindowオブジェクトは、お互いのレルム内で作成されたすべてのオブジェクトに直接アクセスできることを意味するわけではありません。それらは同一オリジンドメインである必要があります。詳細はIsPlatformObjectSameOriginを参照してください。
ウェブプラットフォームには、次の種類のエージェントが存在します:
さまざまなWindowオブジェクトを含んでおり、これらは直接またはdocument.domainを使用して相互にアクセスできる可能性があります。
包含されるエージェントクラスターのオリジンキー付きがtrueである場合、すべてのWindowオブジェクトは同一オリジンであり、直接相互にアクセスでき、document.domainは無効になります。
同一オリジンの二つのWindowオブジェクトは、それぞれが独自のブラウジングコンテキストグループ内にある場合、別の類似オリジンウィンドウエージェント内に存在することがあります。
単一のDedicatedWorkerGlobalScopeを含みます。
単一のSharedWorkerGlobalScopeを含みます。
単一のServiceWorkerGlobalScopeを含みます。
単一のWorkletGlobalScopeオブジェクトを含みます。
特定のワークレットが複数のレルムを持つことがありますが、それぞれのレルムには独自のエージェントが必要です。各レルムが他のレルムと同時に独立してコードを実行できるためです。
ウェブプラットフォームでは、共有ワーカーエージェントと専用ワーカーエージェントのみが、JavaScript
Atomics
APIを使用して、ブロックすることが可能です。
ブロックの可能性を指定してエージェントを作成するには、次の手順を行います:
signifierを新しい一意の内部値とします。
candidateExecutionを新しい候補実行とします。
agentを、新しいエージェントとして作成し、その[[CanBlock]]をcanBlockに設定し、[[Signifier]]をsignifierに設定し、[[CandidateExecution]]をcandidateExecutionに設定し、[[IsLockFree1]]、[[IsLockFree2]]、および[[LittleEndian]]は実装の裁量に任せます。
agentを返します。
レルム realmに対して、[[Signifier]]がrealm.[[AgentSignifier]]であるエージェントがそのレルムのエージェントです。
プラットフォームオブジェクト platformObjectに対する関連エージェントは、platformObjectの関連レルムのエージェントです。
現在のレルムに相当するエージェントは、周囲のエージェントです。
JavaScriptは、エージェントクラスターの概念も定義しています。この標準は、同一オリジンのウィンドウエージェントを取得するやワーカー/ワークレットエージェントを取得するアルゴリズムを使用してエージェントを適切に配置することで、この概念をウェブプラットフォームにマッピングします。
エージェントクラスターの概念は、JavaScriptのメモリモデルを定義するために重要であり、特にどのエージェント間でSharedArrayBufferオブジェクトのバックデータが共有できるかを定義するために重要です。
概念的には、エージェントクラスターの概念は、複数の「スレッド」(エージェント)をグループ化するアーキテクチャに依存しない理想化された「プロセス境界」です。仕様で定義されるエージェントクラスターは、ユーザーエージェントに実装される実際のプロセス境界よりも一般的に制限が厳しいです。これらの理想的な区分を仕様レベルで強制することで、異なる、あるいは変化するユーザーエージェントのプロセスモデルに直面しても、ウェブ開発者が共有メモリに関して互換性のある動作を確認できるようにします。
エージェントクラスターには、クロスオリジン分離モード(クロスオリジン分離モード)が関連付けられており、最初は「なし」です。
エージェントクラスターには、関連付けられたオリジンキー付き(ブール値)があり、最初はfalseです。
以下は、エージェントクラスターの割り当てを定義しています。
エージェントクラスターキーは、サイトまたはオリジンタプルです。ウェブ開発者がオリジンキー付きエージェントクラスターを実現するためのアクションを行わない限り、それはサイトになります。
同等の表現として、エージェントクラスターキーは、スキームとホストまたはオリジンである可能性があります。
同一オリジンのウィンドウエージェントを取得するには、オリジン origin、ブラウジングコンテキストグループ group、およびブール値requestsOACが与えられた場合、次のステップを実行します:
siteをoriginでサイトを取得する結果とします。
keyをsiteとします。
もしgroupのクロスオリジン分離モードが「なし」でない場合、keyをoriginに設定します。
それ以外の場合、もしgroupの過去のエージェントクラスターキーのマップ[origin]が存在する場合、keyをgroupの過去のエージェントクラスターキーのマップ[origin]に設定します。
それ以外の場合:
もしrequestsOACがtrueであれば、keyをoriginに設定します。
groupの過去のエージェントクラスターキーのマップ[origin]をkeyに設定します。
もしgroupのエージェントクラスターのマップ[key]が存在しない場合:
agentClusterを新しいエージェントクラスターとします。
agentClusterのクロスオリジン分離モードをgroupのクロスオリジン分離モードに設定します。
agentClusterのオリジンキー付きを、keyがoriginと等しい場合にはtrue、それ以外の場合はfalseに設定します。
falseを指定してエージェントを作成する結果をagentClusterに追加します。
groupのエージェントクラスターのマップ[key]をagentClusterに設定します。
groupのエージェントクラスターのマップ[key]に含まれる単一の同一オリジンのウィンドウエージェントを返します。
これにより、ブラウジングコンテキストエージェントクラスターごとに1つの同一オリジンのウィンドウエージェントのみが存在することになります。(ただし、専用ワーカーおよびワークレットエージェントは、同じクラスター内に存在する可能性があります。)
以下は、その他の種類のエージェントに対するエージェントクラスターの割り当てを定義します。
ワーカー/ワークレットエージェントを取得するには、環境設定オブジェクトまたはnullのoutside settings、ブール値isTopLevel、およびブール値canBlockが与えられた場合、次のステップを実行します:
agentClusterをnullとします。
もしisTopLevelがtrueであれば:
agentClusterを新しいエージェントクラスターに設定します。
agentClusterのオリジンキー付きをtrueに設定します。
これらのワーカーはオリジンキー付きと見なすことができます。ただし、これは(originAgentClusterがウィンドウに対してオリジンキー付きであることを公開する方法のように)いかなるAPIを通じても公開されません。
それ以外の場合:
agentをcanBlockを指定してエージェントを作成する結果とします。
agentをagentClusterに追加します。
agentを返します。
専用/共有ワーカーエージェントを取得するには、環境設定オブジェクト outside settingsおよびブール値isSharedが与えられた場合、outside settings、isShared、およびtrueを指定してワーカー/ワークレットエージェントを取得する結果を返します。
ワークレットエージェントを取得するには、環境設定オブジェクト outside settingsが与えられた場合、outside settings、false、およびfalseを指定してワーカー/ワークレットエージェントを取得する結果を返します。
サービスワーカーエージェントを取得するには、null、true、およびfalseを指定してワーカー/ワークレットエージェントを取得する結果を返します。
JavaScript仕様は、レルムの概念を導入しており、これはスクリプトが実行されるグローバルな環境を表しています。各レルムには実装定義のグローバルオブジェクトが付随しており、この仕様の多くはそのグローバルオブジェクトとそのプロパティを定義することに費やされています。
ウェブ仕様においては、レルム/グローバルオブジェクトのペアに値やアルゴリズムを関連付けることがしばしば有用です。値が特定の種類のレルムに固有の場合、それらは該当するグローバルオブジェクトに直接関連付けられます。例えば、WindowやWorkerGlobalScopeインターフェースの定義においてです。値が複数のレルムで有用な場合、環境設定オブジェクトの概念を使用します。
最後に、レルム/グローバルオブジェクト/環境設定オブジェクトがまだ存在していない段階で関連する値を追跡する必要がある場合があります(例えば、ナビゲーション中)。これらの値は環境の概念で追跡されます。
環境とは、現在または潜在的な実行環境(例えば、ナビゲーションパラメーターの予約された環境やリクエストの予約されたクライアント)の設定を識別するオブジェクトです。環境には次のフィールドがあります:
この環境を一意に識別する不透明な文字列です。
環境設定オブジェクトにおけるWindowの場合、このURLはDocumentのURLとは異なる場合があります。これは、history.pushState()のように後者を変更するメカニズムがあるためです。
現在は実装定義の値、NULL、またはオリジンです。「最上位」の潜在的な実行環境の場合、これはNULLです(つまり、まだ応答がない場合)。それ以外の場合、これは「最上位」の環境のオリジンです。専用ワーカーやワークレットの場合、これはその作成者の最上位のオリジンです。共有ワーカーやサービスワーカーの場合、これは実装定義の値です。
NULLまたはナビゲーションリクエスト用のターゲットブラウジングコンテキストです。
環境設定が完了したかどうかを示すフラグで、初期状態では設定されていません。
仕様では、環境に対する環境破棄ステップを定義することができます。このステップは、環境を入力として受け取ります。
環境破棄ステップは、実行準備が整うことがない環境、例えば読み込みに失敗した環境に対してのみ実行されます。
環境設定オブジェクトとは、次のアルゴリズムをさらに指定する環境です:
この設定オブジェクトを使用するすべてのスクリプトが共有するJavaScript実行コンテキストであり、つまり、特定のレルム内のすべてのスクリプトが共有するものです。クラシックスクリプトを実行またはモジュールスクリプトを実行する際、この実行コンテキストがJavaScript実行コンテキストスタックの最上位に置かれ、その上にスクリプト固有の実行コンテキストがプッシュされます。(このセットアップにより、ソーステキストモジュールレコードの評価がどのレルムを使用するかを判断できます。)
JavaScriptモジュールをインポートする際に使用されるモジュールマップです。
この環境設定オブジェクトを使用するスクリプトによって呼び出されるAPIがURLを解析するために使用するURLです。
セキュリティチェックで使用されるオリジンです。
セキュリティチェックで使用されるポリシーを含むポリシーコンテナです。
この環境設定オブジェクトを使用するスクリプトがクロスオリジン分離を必要とするAPIを使用できるかどうかを表すブール値です。
パフォーマンス関連のタイムスタンプの基準として使用される数値です。[HRT]
環境設定オブジェクトの責任イベントループは、そのグローバルオブジェクトの関連エージェントのイベントループです。
グローバルオブジェクトとは、レルムの[[GlobalObject]]フィールドであるJavaScriptオブジェクトです。
この仕様では、すべてのレルムは、Window、WorkerGlobalScope、またはWorkletGlobalScopeオブジェクトであるグローバルオブジェクトと共に作成されます。
グローバルオブジェクトには、初期状態ではfalseであるエラーレポートモードブール値があります。
グローバルオブジェクトには、通知待ちの拒否されたプロミスのリストがあり、セットは、初期状態では空のプロミスオブジェクトを含みます。このセットは、そのメンバーに対して強い参照を作成してはならず、実装は、新しいエントリが追加されるときに古いエントリを削除するなど、実装定義の方法でそのサイズを制限することができます。
グローバルオブジェクトには、通知予定の拒否されたプロミスのリストがあり、初期状態では空のプロミスオブジェクトのリストを含みます。
この仕様の定義では、レルム、グローバルオブジェクト、および環境設定オブジェクトの間には常に1対1対1の対応があります:
レルムには[[HostDefined]]フィールドがあり、レルムの設定オブジェクトを含んでいます。
レルムには[[GlobalObject]]フィールドがあり、レルムのグローバルオブジェクトを含んでいます。
この仕様のすべてのグローバルオブジェクトは、対応するレルムの作成中に作成され、グローバルオブジェクトのレルムと呼ばれます。
この仕様のすべてのグローバルオブジェクトは、対応する環境設定オブジェクトと共に作成され、それはその関連する設定オブジェクトと呼ばれます。
環境設定オブジェクトのレルム実行コンテキストのレルムコンポーネントは、環境設定オブジェクトのレルムです。
環境設定オブジェクトのレルムには、[[GlobalObject]]フィールドがあり、環境設定オブジェクトのグローバルオブジェクトを含んでいます。
新しいレルムを作成するには、オプションでグローバルオブジェクトまたはグローバルthisバインディング(またはその両方)の作成を指示して、エージェントagentにおいて次の手順を実行します:
提供されたグローバルオブジェクトおよびグローバルthisバインディングのカスタマイズでInitializeHostDefinedRealm()を実行します。
realm execution contextを、実行中のJavaScript実行コンテキストに設定します。
これは、前の手順で作成されたJavaScript実行コンテキストです。
realm execution contextをJavaScript実行コンテキストスタックから削除します。
realmをrealm execution contextのレルムコンポーネントに設定します。
もしagentのエージェントクラスターのクロスオリジン分離モードが"none"である場合:
globalをrealmのグローバルオブジェクトに設定します。
statusを! global.[[Delete]]("SharedArrayBuffer")に設定します。
Assert:statusがtrueであることを確認します。
これはウェブコンテンツとの互換性のために行われており、将来的には削除される可能性があります。ウェブ開発者はnew WebAssembly.Memory({ shared:true, initial:0, maximum:0 }).buffer.constructorを介して依然としてコンストラクタにアクセスできます。
realm execution contextを返します。
この仕様全体でアルゴリズムのステップを定義する際には、どのrealmを使用するか、または同等に、どのグローバルオブジェクトや環境設定オブジェクトを使用するかを示すことが重要です。一般的に、少なくとも4つの可能性があります。
エントリ、インカンバント、およびカレントの概念が特定の条件なしに使用できる一方で、レレバントの概念は特定のプラットフォームオブジェクトに適用される必要があることに注意してください。
インカンバントとエントリの概念は、新しい仕様では使用すべきではありません。これらは過度に複雑で直感的ではないためです。プラットフォームからほぼすべての既存の使用を削除する作業を進めています。詳細については、issue #1430(インカンバントについて)およびissue #1431(エントリについて)を参照してください。
一般に、ウェブプラットフォームの仕様は、操作されるオブジェクト(通常は現在のメソッドのthis値)に適用されるレレバントの概念を使用すべきです。これは、JavaScript仕様ではカレントが一般的にデフォルトとして使用されることとは一致しません(例:Array.prototype.mapの結果を構築する際に使用されるレルムのArrayコンストラクタを決定する場合など)。しかし、この不一致はプラットフォームに深く根付いているため、今後受け入れる必要があります。
次のページを考えてみてください。a.htmlはブラウザウィンドウにロードされ、b.htmlは示されているようにiframeにロードされ、c.htmlとd.htmlは省略されています(これらは単に空のドキュメントでも構いません)。
<!-- a.html -->
<!DOCTYPE html>
< html lang = "en" >
< title > Entry page</ title >
< iframe src = "b.html" ></ iframe >
< button onclick = "frames[0].hello()" > Hello</ button >
<!--b.html -->
<!DOCTYPE html>
< html lang = "en" >
< title > Incumbent page</ title >
< iframe src = "c.html" id = "c" ></ iframe >
< iframe src = "d.html" id = "d" ></ iframe >
< script >
const c = document. querySelector( "#c" ). contentWindow;
const d = document. querySelector( "#d" ). contentWindow;
window. hello = () => {
c. print. call( d);
};
</ script >
各ページには独自のブラウジングコンテキストがあり、したがって、独自のレルム、グローバルオブジェクト、および環境設定オブジェクトがあります。
レレバントの概念が、一般的にカレントの概念よりも優れたデフォルト選択である理由の一つは、複数回返されるオブジェクトを作成するのにより適しているからです。たとえば、navigator.getBattery()メソッドは、Navigatorオブジェクトの関連するレルムでPromiseを作成します。これは次の影響を持ちます:[BATTERY]
<!-- outer.html -->
<!DOCTYPE html>
< html lang = "en" >
< title > Relevant realm demo: outer page</ title >
< script >
function doTest() {
const promise = navigator. getBattery. call( frames[ 0 ]. navigator);
console. log( promise instanceof Promise); // logs false
console. log( promise instanceof frames[ 0 ]. Promise); // logs true
frames[ 0 ]. hello();
};
もし、getBattery()メソッドのアルゴリズムがカレントレルムを使用していた場合、すべての結果は逆になっていたでしょう。つまり、getBattery()が最初にouter.htmlで呼び出された後、inner.htmlのNavigatorオブジェクトは、outer.htmlのレルムで作成されたPromiseオブジェクトを永続的に保持し、そのため、hello()関数内の呼び出しは「間違った」レルムからのPromiseを返すことになります。これは望ましくないため、アルゴリズムは代わりに関連するレルムを使用し、コメントに示されているような適切な結果を得ています。
このセクションの残りは、エントリ、インカンバント、カレント、およびレレバントの概念を正式に定義することに関するものです。
スクリプトを呼び出す過程で、レルム実行コンテキストがJavaScript実行コンテキストスタックにプッシュまたはポップされますが、これらは他の実行コンテキストと交互に行われます。
これを踏まえ、エントリ実行コンテキストを、JavaScript実行コンテキストスタックに最近プッシュされたレルム実行コンテキストと定義します。エントリレルムは、エントリ実行コンテキストのレルムコンポーネントです。
次に、エントリ設定オブジェクトは、環境設定オブジェクトのエントリレルムのことです。
同様に、エントリグローバルオブジェクトは、グローバルオブジェクトのエントリレルムです。
すべてのJavaScript実行コンテキストは、コード評価の状態の一部として、インカンバント判定時にスキップするカウンター値を含む必要があります。この値は初期状態ではゼロです。コールバックを実行する準備およびコールバックの実行後のクリーンアップの過程で、この値はインクリメントおよびデクリメントされます。
すべてのイベントループには、初期状態では空のバックアップインカンバント設定オブジェクトスタックが関連付けられています。大まかに言えば、これは、スタック上にオーサーコードが存在しない場合にインカンバント設定オブジェクトを決定するために使用されますが、オーサーコードは現在のアルゴリズムが何らかの形で実行される原因となっています。コールバックを実行する準備およびコールバックの実行後のクリーンアップの過程で、このスタックが操作されます。[WEBIDL]
Web IDLが使用されてオーサーコードを呼び出す場合、またはHostEnqueuePromiseJobがプロミスジョブを呼び出す場合、これらはインカンバント設定オブジェクトを決定するために、次のアルゴリズムを使用して関連するデータを追跡します。
環境設定オブジェクトに基づいてコールバックを実行する準備をするには、次の手順を実行します。
settingsをバックアップインカンバント設定オブジェクトスタックにプッシュします。
contextをトップのスクリプトを持つ実行コンテキストとして定義します。
contextがnullでない場合、contextのインカンバント判定時にスキップするカウンターをインクリメントします。
環境設定オブジェクトを用いてコールバックの実行後にクリーンアップするには、次の手順を実行します。
contextをトップのスクリプトを持つ実行コンテキストとして定義します。
これは、コールバックを実行する準備の対応する呼び出し内でのトップのスクリプトを持つ実行コンテキストと同じになります。
contextがnullでない場合、contextのインカンバント判定時にスキップするカウンターをデクリメントします。
アサート:バックアップインカンバント設定オブジェクトスタックの最上位のエントリがsettingsです。
settingsをバックアップインカンバント設定オブジェクトスタックから削除します。
ここで、トップのスクリプトを持つ実行コンテキストとは、JavaScript実行コンテキストスタックの最上位のエントリであり、nullでないScriptOrModuleコンポーネントを持つエントリ、またはJavaScript実行コンテキストスタックにそのようなエントリが存在しない場合はnullとなります。
これにより、インカンバント設定オブジェクトが次のように決定されます。
contextをトップのスクリプトを持つ実行コンテキストとして定義します。
contextがnullである場合、またはcontextのインカンバント判定時にスキップするカウンターがゼロより大きい場合、次の手順を実行します。
アサート:バックアップインカンバント設定オブジェクトスタックが空でないこと。
これは、スクリプトの呼び出しやWeb IDLのコールバックの呼び出しによってトリガーされなかったアルゴリズム内でインカンバント設定オブジェクトを取得しようとした場合に失敗します。たとえば、著者コードが関与していない状態でイベントループの一部として定期的に実行されたアルゴリズム内でインカンバント設定オブジェクトを取得しようとした場合、インカンバントの概念は使用できません。
バックアップインカンバント設定オブジェクトスタックの最上位のエントリを返します。
contextのレルムコンポーネントの設定オブジェクトを返します。
次に、インカンバントレルムは、環境設定オブジェクトのレルムです。
同様に、インカンバントグローバルオブジェクトは、グローバルオブジェクトのインカンバント設定オブジェクトです。
次の一連の例は、さまざまなメカニズムがどのようにしてインカンバントの概念の定義に貢献するかを明確にするために意図されています。
次のスターター例を考えてみましょう。
<!DOCTYPE html>
< iframe ></ iframe >
< script >
frames[ 0 ]. postMessage( "some data" , "*" );
</ script >
ここで注目すべき環境設定オブジェクトは2つあります。1つはwindow、もう1つはframes[0]のものです。問題は、postMessage()アルゴリズムが実行されるときのインカンバント設定オブジェクトが何であるかということです。
それはwindowのものであるべきです。これは、アルゴリズムを実行する原因となった著者のスクリプトがframes[0]ではなくwindowで実行されているという直感的な考えを捉えるためです。これは理にかなっています。windowのpost
message手順は、結果として生じるsourceプロパティを決定するためにincumbent設定オブジェクトを使用します。そして、この場合、メッセージのソースは間違いなくwindowです。
次に、上記の手順がどのようにして直感的に望まれるwindowの関連設定オブジェクトの結果をもたらすかを説明しましょう。
ウィンドウポストメッセージの手順がインカンバント設定オブジェクトを調べるとき、トップのスクリプトを持つ実行コンテキストは、スクリプト要素に対応するものです。これは、JavaScript実行コンテキストスタックにスクリプト評価の一部としてプッシュされました。Web IDLのコールバック呼び出しは関与していないため、このコンテキストのインカンバント判定時にスキップするカウンターはゼロであり、そのためインカンバント設定オブジェクトが決定されます。結果はwindowの環境設定オブジェクトです。
(frames[0]の環境設定オブジェクトが、postMessage()メソッドが呼び出されたときのthisの関連設定オブジェクトであることに注意してください。そして、これがメッセージのターゲットの決定に関与しています。一方で、インカンベントはソースの決定に使用されます。)
次のより複雑な例を考えてみましょう。
<!DOCTYPE html>
< iframe ></ iframe >
< script >
const bound = frames[ 0 ]. postMessage. bind( frames[ 0 ], "some data" , "*" );
window. setTimeout( bound);
</ script >
この例は前の例と非常に似ていますが、Function.prototype.bindやsetTimeout()による追加の間接参照があります。しかし、答えは同じであるべきです。非同期的にアルゴリズムを呼び出すことは、インカンバントの概念を変更するべきではありません。
今回は、結果はより複雑なメカニズムに関係します。
boundがWeb IDLコールバックタイプに変換されると、インカンバント設定オブジェクトはwindowに対応するものとなります(上記のスターター例と同様)。Web
IDLはこれをコールバック値のコールバックコンテキストとして保存します。
setTimeout()によって投稿されたタスクが実行されると、そのタスクのアルゴリズムはWeb IDLを使用して保存されたコールバック値を呼び出します。Web IDLは、上述のコールバックを実行する準備アルゴリズムを呼び出します。これにより、保存されたコールバックコンテキストがバックアップインカンバント設定オブジェクトスタックにプッシュされます。この時点(タイマータスク内)では、スタック上にオーサーコードは存在せず、トップのスクリプトを持つ実行コンテキストはnullであり、インカンバント判定時にスキップするカウンターは何もインクリメントされません。
コールバックを呼び出すと、boundが呼び出され、それがpostMessage()メソッドをframes[0]で呼び出します。postMessage()アルゴリズムがインカンバント設定オブジェクトを調べるとき、スタック上にオーサーコードは存在せず、バウンド関数がビルトインメソッドを直接呼び出すだけです。そのため、トップのスクリプトを持つ実行コンテキストはnullになります。JavaScript実行コンテキストスタックには、postMessage()に対応する実行コンテキストしか含まれておらず、その下にはスクリプト評価コンテキストや類似のものはありません。
ここで、バックアップインカンバント設定オブジェクトスタックが利用されます。前述のように、最上位のエントリはwindowの関連設定オブジェクトであり、それがpostMessage()アルゴリズムの実行中にインカンバント設定オブジェクトとして使用されます。
最後に、さらに複雑な例を考えてみましょう。
<!-- a.html -->
<!DOCTYPE html>
< button > click me</ button >
< iframe ></ iframe >
< script >
const bound = frames[ 0 ]. location. assign. bind( frames[ 0 ]. location, "https://example.com/" );
document. querySelector( "button" ). addEventListener( "click" , bound);
</ script >
<!-- b.html -->
<!DOCTYPE html>
< iframe src = "a.html" ></ iframe >
< script >
const iframe = document. querySelector( "iframe" );
iframe. onload = function onLoad() {
iframe. contentWindow. document. querySelector( "button" ). click();
};
</ script >
ここでも、2つの注目すべき環境設定オブジェクトが関わっています。1つはa.html、もう1つはb.htmlのものです。location.assign()メソッドがLocationオブジェクトのナビゲートアルゴリズムをトリガーしたとき、インカンバント設定オブジェクトは何になるのでしょうか?以前と同様、直感的にはa.htmlのものになるべきです。clickリスナーは元々a.htmlによってスケジュールされたものであり、b.htmlが関与してリスナーが発火したとしても、その責任はa.htmlにあります。
コールバックのセットアップは前の例と似ています。boundがWeb IDLコールバックタイプに変換されると、インカンバント設定オブジェクトはa.htmlに対応するものであり、これがコールバックのコールバックコンテキストとして保存されます。
click()メソッドがb.html内で呼び出されると、それはイベントをa.html内のボタンにディスパッチします。今回、イベントディスパッチの一部としてコールバックを実行する準備アルゴリズムが実行されるとき、スタック上にはオーサーコードが存在します。トップのスクリプトを持つ実行コンテキストはonLoad関数のものであり、そのインカンバント判定時にスキップするカウンターがインクリメントされます。さらに、a.htmlの環境設定オブジェクト(EventHandlerのコールバックコンテキストとして保存されている)がバックアップインカンバント設定オブジェクトスタックにプッシュされます。
さて、Locationオブジェクトのナビゲートアルゴリズムがインカンバント設定オブジェクトを調べるとき、トップのスクリプトを持つ実行コンテキストは依然としてonLoad関数のものであり(コールバックとしてバウンド関数を使用しているため)、そのインカンバント判定時にスキップするカウンターの値は1です。しかし、ここで再びバックアップインカンバント設定オブジェクトスタックにフォールバックします。これにより、予想通りa.htmlの環境設定オブジェクトが得られます。
これは、iframeがa.html内でナビゲートする場合でも、a.html自体がソースドキュメントとして使用されることを意味し、これによりリクエストクライアントなどが決定されます。これは、インカンバントの概念がWebプラットフォームで正当化される唯一のケースかもしれません。それ以外の場合、インカンバントを使用することの結果は単に混乱を招くものであり、将来的にはこれらを現在または関連に適切に切り替えることを望んでいます。
JavaScript仕様は、現在のレルム("current Realm Record"とも呼ばれる)を定義しています。[JAVASCRIPT]
次に、現在の設定オブジェクトは、環境設定オブジェクトの現在のレルムです。
同様に、現在のグローバルオブジェクトは、グローバルオブジェクトの現在のレルムです。
関連レルムとは、プラットフォームオブジェクトの[[Realm]]フィールドの値です。
次に、関連設定オブジェクトとは、プラットフォームオブジェクト oの環境設定オブジェクトの、関連レルムです。
同様に、関連グローバルオブジェクトとは、プラットフォームオブジェクト oのグローバルオブジェクトの、関連レルムです。
スクリプトが有効とは、環境設定オブジェクト settingsに対して、以下の条件がすべて真であるときです。
Windowオブジェクトでないか、settingsのグローバルオブジェクトの関連Documentのアクティブなサンドボックスフラグセットに、サンドボックス化されたスクリプトのブラウジングコンテキストフラグが設定されていないこと。
スクリプトが無効とは、環境設定オブジェクトに対して、スクリプトが有効ではないとき、すなわち上記のいずれかの条件が偽であるときです。
スクリプトが有効とは、ノードnodeのノードドキュメントのブラウジングコンテキストがnullでなく、かつnodeの関連設定オブジェクトに対してスクリプトが有効であるときです。
スクリプトが無効とは、スクリプトが有効でないとき、すなわちそのノードドキュメントのブラウジングコンテキストがnullであるか、nodeの関連設定オブジェクトに対してスクリプトが無効であるときです。
環境 environmentは、次のアルゴリズムがtrueを返す場合、セキュアなコンテキストです。
もしenvironmentが環境設定オブジェクトである場合:
globalをenvironmentのグローバルオブジェクトとします。
もしglobalがWorkerGlobalScopeである場合:
もしglobalのオーナーセット[0]の関連設定オブジェクトがセキュアなコンテキストである場合、trueを返します。
すべての項目が一貫しているはずなので、0番目の項目だけを確認すれば十分です。
falseを返します。
もしglobalがWorkletGlobalScopeである場合、trueを返します。
ワークレットはセキュアなコンテキストでのみ作成できます。
もしURLが潜在的に信頼できるかどうかの結果がenvironmentのトップレベルの作成URLに対して「Potentially Trustworthy」である場合、trueを返します。
falseを返します。
環境がセキュアなコンテキストでない場合、それは非セキュアなコンテキストです。
スクリプトは、次の2つの可能性がある構造体の一つです(具体的には、クラシックスクリプトまたはモジュールスクリプト)。すべてのスクリプトは次のものを持っています:
同じコンテキストで他のスクリプトと共有されるさまざまな設定を含む環境設定オブジェクト。
次のいずれか:
スクリプトレコード、クラシックスクリプトの場合。
null、これはパースエラーを表します。
JavaScript値。この値はレコードがnullである場合にのみ意味を持ち、対応するスクリプトのソーステキストがパースできなかったことを示します。
この値はスクリプト作成時の即時パースエラーを内部的に追跡するために使用され、直接使用されることはありません。代わりに、このスクリプトの「何が問題だったのか」を判断する際には再スローすべきエラーを参照してください。
評価の成功を妨げるエラーを表すJavaScript値。スクリプトを実行しようとするたびに再スローされます。
これはスクリプトのパースエラーである場合がありますが、モジュールスクリプトの場合、それはその依存関係の1つのパースエラーであるか、モジュール識別子を解決するときのエラーである場合があります。
この例外値はJavaScript仕様で提供されているため、nullになることはなく、エラーが発生していないことを示すためにnullが使用されます。
nullまたはURLの基本URL。これはモジュール識別子の解決に使用されます。nullでない場合、外部スクリプトの場合はスクリプトが取得されたURL、インラインスクリプトの場合は含まれているドキュメントのドキュメントベースURLのいずれかになります。
クラシックスクリプトは、次の追加の項目を持つタイプのスクリプトです:
ブール値であり、trueの場合、このスクリプトのエラー情報は提供されません。これはクロスオリジンスクリプトのエラーをミュートするために使用され、プライベートな情報が漏れるのを防ぎます。
モジュールスクリプトは、別のタイプのスクリプトです。追加の項目はありません。
モジュールスクリプトは次の3つのタイプに分類できます:
モジュールスクリプトは、JavaScriptモジュールスクリプトであり、そのレコードがソーステキストモジュールレコードである場合です。
モジュールスクリプトは、CSSモジュールスクリプトであり、そのレコードがシンセティックモジュールレコードであり、CSSモジュールスクリプトを作成するアルゴリズムによって作成された場合です。CSSモジュールスクリプトは、パースされたCSSスタイルシートを表します。
モジュールスクリプトは、JSONモジュールスクリプトであり、そのレコードがシンセティックモジュールレコードであり、JSONモジュールスクリプトを作成するアルゴリズムによって作成された場合です。JSONモジュールスクリプトは、パースされたJSONドキュメントを表します。
CSSスタイルシートおよびJSONドキュメントは依存モジュールをインポートせず、評価時に例外をスローしないため、フェッチオプションおよびベースURLはCSSモジュールスクリプトおよびJSONモジュールスクリプトでは常にnullです。
アクティブスクリプトは、次のアルゴリズムによって決定されます:
recordをGetActiveScriptOrModule()に設定します。
もしrecordがnullであれば、nullを返します。
recordの[[HostDefined]]を返します。
アクティブスクリプトの概念は、import()機能でのみ使用され、相対モジュール識別子を解決するために使用するベースURLを決定します。
このセクションでは、スクリプトをフェッチするためのいくつかのアルゴリズムを紹介します。これらのアルゴリズムは、さまざまな必要な入力を受け取り、クラシックスクリプトやモジュールスクリプトとして結果を生成します。
スクリプトフェッチオプションは、次の構造体を持つ構造体です:
初回フェッチおよびインポートされたモジュールのフェッチに使用される暗号化ノンスメタデータ
初回フェッチに使用されるインテグリティメタデータ
初回フェッチおよびインポートされたモジュールのフェッチに使用されるパーサメタデータ
初回フェッチ(モジュールスクリプトの場合)およびインポートされたモジュールのフェッチ(モジュールスクリプトとクラシックスクリプトの両方の場合)に使用されるクレデンシャルモード
初回フェッチおよびインポートされたモジュールのフェッチに使用されるリファラーポリシー
このポリシーは、モジュールスクリプトのレスポンスが受信された後に変化することがあります。これは、レスポンスからリファラーポリシーを解析し、モジュール依存関係をフェッチするときに使用されます。
初回フェッチおよびインポートされたモジュールのフェッチに使用されるレンダーブロッキングのブール値です。特に指定がない限り、その値はfalseです。
初回フェッチに使用される優先度
「import()」機能を介して、クラシックスクリプトがモジュールスクリプトをインポートできることを思い出してください。
デフォルトのクラシックスクリプトフェッチオプションは、スクリプトフェッチオプションであり、その暗号化ノンスは空の文字列、インテグリティメタデータは空の文字列、パーサメタデータは「not-parser-inserted」、クレデンシャルモードは「same-origin」、リファラーポリシーは空の文字列、そしてフェッチ優先度は「auto」です。
次のものを与えられた場合:
requestの暗号化ノンスメタデータをoptionsの暗号化ノンスに設定し、インテグリティメタデータをoptionsのインテグリティメタデータに設定し、パーサメタデータをoptionsのパーサメタデータに設定し、リファラーポリシーをoptionsのリファラーポリシーに設定し、レンダーブロッキングをoptionsのレンダーブロッキングに設定し、優先度をoptionsのフェッチ優先度に設定します。
requestの暗号化ノンスメタデータをoptionsの暗号化ノンスに設定し、インテグリティメタデータをoptionsのインテグリティメタデータに設定し、パーサメタデータをoptionsのパーサメタデータに設定し、クレデンシャルモードをoptionsのクレデンシャルモードに設定し、リファラーポリシーをoptionsのリファラーポリシーに設定し、レンダーブロッキングをoptionsのレンダーブロッキングに設定し、優先度をoptionsのフェッチ優先度に設定します。
子孫スクリプトフェッチオプションを取得するためには、次の手順を実行します。
originalOptionsのコピーをnewOptionsとします。
integrityを空の文字列に設定します。
もしsettingsObjectのグローバルオブジェクトがWindowオブジェクトであるなら、integrityをurlとsettingsObjectを使用してモジュールインテグリティメタデータを解決する結果に設定します。
newOptionsのインテグリティメタデータをintegrityに設定します。
newOptionsのフェッチ優先度を「auto」に設定します。
newOptionsを返します。
モジュールインテグリティメタデータを解決するためには、次の手順を実行します。
settingsObjectのグローバルオブジェクトがWindowオブジェクトであることをアサートします。
settingsObjectのグローバルオブジェクトのインポートマップをmapとします。
mapのインテグリティ[url]を返します。
以下のいくつかのアルゴリズムは、フェッチフックを実行するアルゴリズムでカスタマイズできます。このアルゴリズムは、リクエスト、ブール値のisTopLevel、およびprocessCustomFetchResponseアルゴリズムを取ります。このアルゴリズムは、レスポンスとnull(失敗時)またはレスポンスボディを含むバイトシーケンスを使用してprocessCustomFetchResponseを実行します。isTopLevelは、すべてのクラシックスクリプトのフェッチ、および外部モジュールスクリプトグラフをフェッチするまたはモジュールワーカースクリプトグラフをフェッチする際の最初のフェッチでtrueになりますが、グラフ全体またはimport()式で遭遇したインポート文によるフェッチの場合はfalseです。
これらのアルゴリズム固有のカスタマイズの上に、独自のカスタマイズをレイヤリングするには、指定されたリクエストを変更し、フェッチを実行し、その後、結果となるレスポンスの特定のバリデーションを実行するフェッチフックを実行するフックを提供します(バリデーションが失敗した場合はネットワークエラーで完了します)。
このフックは、レスポンスのキャッシュを保持し、フェッチを全く行わないといった、より微妙なカスタマイズにも使用できます。
Service Workersは、フックのオプションに独自のオプションを指定してこれらのアルゴリズムを実行する例です。[SW]
では、アルゴリズム自体に移りましょう。
クラシックスクリプトをフェッチするためには、次の手順を実行します。
潜在的なCORSリクエストを作成する結果をrequestとし、url、"script"、およびcorsSettingを指定します。
requestのクライアントをsettingsObjectに設定します。
requestのイニシエータタイプを"script"に設定します。
クラシックスクリプトリクエストの設定を実行し、requestおよびoptionsを設定します。
フェッチを実行し、requestのresponseおよびnull、失敗、またはbodyBytesとしてprocessResponseConsumeBodyステップを実行します。
responseは、CORS同一オリジンまたはCORS異なるオリジンのどちらかです。これにより、エラーレポートの方法が変わります。
responseをresponseの非安全なレスポンスに設定します。
以下のいずれかがtrueである場合:
その場合、onCompleteをnullで実行し、これらのステップを中止します。
歴史的な理由から、このアルゴリズムには、他のスクリプトフェッチアルゴリズムとは異なり、MIMEタイプチェックが含まれていません。
potentialMIMETypeForEncodingを、MIMEタイプを抽出する結果として設定し、responseのヘッダーリストを指定します。
encodingを、potentialMIMETypeForEncodingおよびencodingを指定してレガシーエンコーディングを抽出する結果に設定します。
これにより、MIMEタイプエッセンスが無視されることになります。
sourceTextを、デコードする結果として設定し、bodyBytesをUnicodeにデコードし、encodingをフォールバックエンコーディングとして使用します。
このデコードアルゴリズムは、ファイルにBOMが含まれている場合、encodingをオーバーライドします。
mutedErrorsを、responseがCORS異なるオリジンであった場合はtrue、それ以外の場合はfalseに設定します。
scriptをクラシックスクリプトを作成する結果として設定し、sourceText、settingsObject、responseのURL、options、mutedErrors、およびurlを指定します。
クラシックワーカースクリプトをフェッチするには、次の手順を実行します。
requestを新しいリクエストとして設定し、そのURLをurl、クライアントをfetchClient、デスティネーションをdestination、イニシエータタイプを"other"、モードを"same-origin"、クレデンシャルモードを"same-origin"、パーサーメタデータを"not parser-inserted"、URLクレデンシャルフラグをセットします。
もしperformFetchが指定されている場合は、performFetchを使用し、requestと、以下に定義するprocessResponseConsumeBodyを使って実行します。
それ以外の場合は、フェッチを実行し、requestを使用し、processResponseConsumeBodyを以下に定義する通りに設定します。
いずれの場合も、processResponseConsumeBodyを以下のアルゴリズムに基づいて実行します。レスポンスresponseと、null、失敗、またはバイトシーケンスbodyBytesを引数として受け取ります。
responseをresponseの非安全なレスポンスに設定します。
以下のいずれかがtrueである場合:
その場合、onCompleteをnullで実行し、これらのステップを中止します。
以下のすべてがtrueである場合:
responseのURLのスキームがHTTP(S)スキームである場合;
responseのヘッダーリストからMIMEタイプを抽出する結果がJavaScript MIMEタイプでない場合;
その場合、onCompleteをnullで実行し、これらのステップを中止します。
他のフェッチスキームは歴史的なWeb互換性の理由でMIMEタイプのチェックから除外されています。将来的にこれを強化できるかもしれません。詳しくはissue #3255を参照してください。
sourceTextを、UTF-8デコードでbodyBytesから得られる結果として設定します。
scriptをクラシックスクリプトを作成する結果として設定し、sourceText、settingsObject、responseのURL、およびデフォルトのクラシックスクリプトフェッチオプションを使用します。
onCompleteをscriptで実行します。
次の手順を実行して、URL url、環境設定オブジェクト settingsObject、および任意のフェッチフックを実行 performFetchを使って、クラシックワーカーインポートスクリプトをフェッチします。アルゴリズムは成功時にクラシックスクリプトを返し、失敗時には例外をスローします。
responseをnullに設定します。
bodyBytesをnullに設定します。
requestを新しいリクエストとして設定し、そのURLをurl、クライアントをsettingsObject、デスティネーションを"script"、イニシエータタイプを"other"、パーサーメタデータを"not parser-inserted"に設定し、URLクレデンシャルフラグをセットします。
もしperformFetchが指定されている場合は、performFetchを使用して、request、isTopLevel、および以下に定義するprocessResponseConsumeBodyを実行します。
それ以外の場合は、フェッチを実行し、requestを使用し、processResponseConsumeBodyを以下に定義する通りに設定します。
いずれの場合も、processResponseConsumeBodyを以下のアルゴリズムに基づいて実行します。レスポンスresと、null、失敗、またはバイトシーケンスbbを引数として受け取ります。
bodyBytesをbbに設定します。
responseをresに設定します。
responseがnullでなくなるまで一時停止します。
このアルゴリズムでは、他のセクションのアルゴリズムとは異なり、フェッチプロセスは同期的に行われます。
responseをresponseの非安全なレスポンスに設定します。
次のいずれかがtrueの場合:
bodyBytesがnullまたは失敗である場合;
responseのヘッダーリストからMIMEタイプを抽出する結果がJavaScript MIMEタイプでない場合;
その場合、"NetworkError"のDOMExceptionをスローします。
sourceTextを、UTF-8デコードを使用してbodyBytesから得た結果に設定します。
もしresponseがCORSクロスオリジンであればmutedErrorsをtrueに、そうでない場合はfalseに設定します。
scriptを、sourceText、settingsObject、responseのURL、デフォルトクラシックスクリプトフェッチオプション、およびmutedErrorsを使ってクラシックスクリプトを作成した結果に設定します。
scriptを返します。
外部モジュールスクリプトグラフを取得するために、URL url、環境設定オブジェクト settingsObject、スクリプトフェッチオプション options、およびアルゴリズム onComplete を指定して、次の手順を実行します。onComplete は、null(失敗時)またはモジュールスクリプト(成功時)を受け入れるアルゴリズムでなければなりません。
settingsObjectに対して、インポートマップをさらに許可しないを実行します。
url、settingsObject、"script"、options、settingsObject、"client"、trueを指定して、単一のモジュールスクリプトを取得します。次の手順をresultを与えて実行します。
resultがnullの場合、onCompleteをnullで実行し、これらの手順を中止します。
resultに対して、子孫を取得してリンクするを、settingsObject、"script"、およびonCompleteを指定して実行します。
モジュールプリロードモジュールスクリプトグラフを取得するために、URL url、宛先 destination、環境設定オブジェクト settingsObject、スクリプトフェッチオプション options、およびアルゴリズム onComplete を指定して、次の手順を実行します。onComplete は、null(失敗時)またはモジュールスクリプト(成功時)を受け入れるアルゴリズムでなければなりません。
settingsObjectに対して、インポートマップをさらに許可しないを実行します。
url、settingsObject、destination、options、settingsObject、"client"、trueを指定して、単一のモジュールスクリプトを取得します。次の手順をresultを与えて実行します。
resultをonCompleteに与えて実行します。
resultがnullでない場合、settingsObject、destination、および空のアルゴリズムを指定して、任意で子孫を取得してリンクするを実行します。
インラインモジュールスクリプトグラフを取得するために、文字列 sourceText、URL baseURL、環境設定オブジェクト settingsObject、スクリプトフェッチオプション options、およびアルゴリズム onComplete を指定して、次の手順を実行します。onComplete は、null(失敗時)またはモジュールスクリプト(成功時)を受け入れるアルゴリズムでなければなりません。
settingsObjectに対して、インポートマップをさらに許可しないを実行します。
sourceText、settingsObject、baseURL、およびoptionsを使用して、JavaScriptモジュールスクリプトを作成します。
settingsObject、"script"、およびonCompleteを指定して、子孫を取得してリンクするを実行します。
モジュールワーカースクリプトグラフを取得するために、URL url、環境設定オブジェクト fetchClient、宛先 destination、認証モード credentialsMode、環境設定オブジェクト settingsObject、およびアルゴリズム onComplete を指定して、ワークレット/モジュールワーカースクリプトグラフを取得します。 url、fetchClient、destination、credentialsMode、settingsObject、およびonCompleteを指定します。
ワークレットスクリプトグラフを取得するために、URL url、環境設定オブジェクト fetchClient、宛先 destination、認証モード credentialsMode、環境設定オブジェクト settingsObject、モジュール応答マップ moduleResponsesMap、およびアルゴリズム onComplete を指定して、ワークレット/モジュールワーカースクリプトグラフを取得します。 url、fetchClient、destination、credentialsMode、settingsObject、onComplete、および次のフェッチフックを実行するを指定します。requestとカスタムフェッチ応答を処理する。
requestのURLをrequestURLに設定します。
もしmoduleResponsesMap[requestURL]が"fetching"である場合、そのエントリの値が変わるまで並列で待機し、その後タスクをキューに入れ、ネットワーキングタスクソースで以下の手順を実行します。
もしmoduleResponsesMap[requestURL]が存在する場合:
moduleResponsesMap[requestURL]をcachedに設定します。
processCustomFetchResponseをcached[0]とcached[1]で実行します。
終了します。
moduleResponsesMap[requestURL]を"fetching"に設定します。
フェッチをrequestで実行し、次の手順を応答 responseおよびnull、失敗、またはバイトシーケンス bodyBytesを与えて実行します。
moduleResponsesMap[requestURL]を(response、bodyBytes)に設定します。
processCustomFetchResponseをresponseおよびbodyBytesで実行します。
これらのアルゴリズムは、この仕様の内部使用のみを目的としており、外部モジュールスクリプトグラフを取得するや、上記の他の類似の概念の一部として使用されるもので、他の仕様によって直接使用されるべきではありません。
この図は、これらのアルゴリズムが上記のアルゴリズムや互いにどのように関連しているかを示しています。
次の手順に従って、ワークレット/モジュールワーカースクリプトグラフを取得するために、URL url、環境設定オブジェクト fetchClient、宛先 destination、認証モード credentialsMode、環境設定オブジェクト settingsObject、アルゴリズム onComplete、およびオプションでフェッチフックを実行する performFetchを指定して、次の手順を実行します。onComplete は、null(失敗時)またはモジュールスクリプト(成功時)を受け入れるアルゴリズムでなければなりません。
スクリプトフェッチオプションをoptionsに設定します。その暗号化ナンスは空文字列、インテグリティメタデータは空文字列、パーサーメタデータは"not-parser-inserted"、認証モードはcredentialsMode、リファラーポリシーは空文字列、そしてフェッチ優先度は"auto"です。
url、fetchClient、destination、options、settingsObject、"client"、true、および以下で定義されるonSingleFetchCompleteを指定して、単一のモジュールスクリプトをフェッチします。performFetchが指定された場合、それも渡します。
onSingleFetchCompleteはresultが与えられた場合、次のアルゴリズムです:
もしresultがnullであれば、onCompleteを実行し、nullを渡してこれらの手順を中止します。
fetchClient、destination、およびonCompleteを指定して、モジュールスクリプトの子孫を取得してリンクする result。performFetchが指定された場合、それも渡します。
モジュールスクリプトの子孫を取得してリンクするために、モジュールスクリプト moduleScript、環境設定オブジェクト fetchClient、宛先 destination、アルゴリズム onComplete、およびオプションでフェッチフックを実行する performFetchを指定して、次の手順を実行します。onComplete は、null(失敗時)またはモジュールスクリプト(成功時)を受け入れるアルゴリズムでなければなりません。
moduleScriptのレコードをrecordに設定します。
もしrecordがnullであれば、次の手順を実行します:
stateをRecord { [[ParseError]]: null, [[Destination]]: destination, [[PerformFetch]]: null, [[FetchClient]]: fetchClient } に設定します。
もしperformFetchが指定された場合、state.[[PerformFetch]]をperformFetchに設定します。
record.LoadRequestedModules(state)をloadingPromiseに設定します。
この手順は、すべてのモジュールのトランジティブ依存関係を再帰的にロードします。
完了時にloadingPromiseを実行し、次の手順を実行します:
拒否時にloadingPromiseを実行し、次の手順を実行します:
もしstate.[[ParseError]]がnullでなければ、moduleScriptの再スローするエラーをstate.[[ParseError]]に設定し、onCompleteを実行してmoduleScriptを渡します。
それ以外の場合、onCompleteを実行してnullを渡します。
state.[[ParseError]]がnullの場合、loadingPromiseがロードエラーにより拒否されたことを示します。
単一のモジュールスクリプトを取得するために、URL url、環境設定オブジェクト fetchClient、宛先 destination、スクリプトフェッチオプション options、環境設定オブジェクト settingsObject、参照元 referrer、オプションのモジュールリクエストレコード moduleRequest、isTopLevelというブール値、アルゴリズム onComplete、およびオプションのフェッチフックを実行する performFetchを指定して、次の手順を実行します。onComplete は、null(失敗時)またはモジュールスクリプト(成功時)を受け入れるアルゴリズムでなければなりません。
moduleTypeを "javascript" に設定します。
もしmoduleRequestが与えられていた場合、moduleTypeをモジュールリクエストからのモジュールタイプの手順に従って、moduleRequestを渡して実行した結果に設定します。
Assert: moduleTypeとsettingsObjectを指定してモジュールタイプの許可の手順を実行した結果がtrueであることを確認します。そうでなければ、moduleRequest.[[Attributes]]をJavaScriptモジュールスクリプトを作成するまたは単一のインポートされたモジュールスクリプトを取得する時に失敗が発生してこのポイントに到達しなかったはずです。
moduleMapをsettingsObjectのモジュールマップに設定します。
もしmoduleMap[(url, moduleType)]が"fetching"である場合、それが変更されるまで並行して待機し、その後次の手順を実行するためにタスクをキューに入れます。
もしmoduleMap[(url, moduleType)]が存在する場合、onCompleteを実行し、moduleMap[(url, moduleType)]を渡して返します。
設定する moduleMap[(url, moduleType)] を
"fetching"に。
requestを新しいリクエストとして、requestのURLはurl、モードは"cors"、参照元はreferrer、およびクライアントはfetchClientに設定します。
モジュールタイプからのフェッチの宛先の手順をdestinationとmoduleTypeを渡して実行した結果をrequestの宛先に設定します。
もしdestinationが"worker"、"sharedworker"、または"serviceworker"であり、isTopLevelがtrueである場合、requestのモードを"same-origin"に設定します。
requestの開始者タイプを"script"に設定します。
モジュールスクリプトリクエストの設定の手順をrequestとoptionsに対して実行します。
もしperformFetchが与えられていた場合、request、isTopLevel、および以下で定義されるprocessResponseConsumeBodyを指定してperformFetchを実行します。
そうでない場合は、フェッチをrequestに対してprocessResponseConsumeBodyを以下で定義されるように設定して実行します。
どちらの場合も、processResponseConsumeBodyをresponseとしてresponseがnull、失敗、またはバイトシーケンス bodyBytesが与えられた場合、次のアルゴリズムを実行します。
responseは常にCORS同一オリジンです。
次のいずれかがtrueであれば:
その場合は、設定 moduleMap[(url, moduleType)] にnullを指定し、onCompleteをnullを指定して実行し、これらの手順を中止します。
sourceTextをbodyBytesに対してUTF-8デコードした結果に設定します。
mimeTypeをresponseの抽出されたMIMEタイプから取得した結果に設定します。
moduleScriptをnullに設定します。
referrerPolicyをresponseの`Referrer-Policy`ヘッダーを解析した結果に設定します。[REFERRERPOLICY]
もしreferrerPolicyが空の文字列でない場合、optionsの参照元ポリシーをreferrerPolicyに設定します。
もしmimeTypeがJavaScript
MIMEタイプであり、moduleTypeが"javascript"である場合、moduleScriptをJavaScriptモジュールスクリプトの作成に基づいて、sourceText、settingsObject、responseのURL、およびoptionsを指定して実行した結果に設定します。
もしmimeTypeのMIMEタイプのエッセンスが"text/css"であり、moduleTypeが"css"である場合、moduleScriptをCSSモジュールスクリプトの作成に基づいて、sourceTextおよびsettingsObjectを指定して実行した結果に設定します。
もしmimeTypeがJSON
MIMEタイプであり、moduleTypeが"json"である場合、moduleScriptをJSONモジュールスクリプトの作成に基づいて、sourceTextおよびsettingsObjectを指定して実行した結果に設定します。
設定 moduleMap[(url, moduleType)] を moduleScriptに、そしてonCompleteをmoduleScriptを指定して実行します。
モジュールマップがリクエストURLをキーとして使用する一方で、スクリプトの基本URLがモジュールスクリプトに設定されているのは意図的です。前者はフェッチの重複排除に使用され、後者はURL解決に使用されます。
単一のインポートされたモジュールスクリプトを取得するために、URL url、環境設定オブジェクト fetchClient、宛先 destination、スクリプトフェッチオプション options、環境設定オブジェクト settingsObject、参照元 referrer、モジュールリクエストレコード moduleRequest、アルゴリズム onComplete、およびオプションのフェッチフックを実行する performFetchを指定して、次の手順を実行します。onComplete は、null(失敗時)またはモジュールスクリプト(成功時)を受け入れるアルゴリズムでなければなりません。
アサート: moduleRequest.[[Attributes]]
に"type"以外のキーを持つレコードが含まれていないことを確認します。なぜなら、HostGetSupportedImportAttributesで"type"属性のみを要求したためです。
moduleTypeをモジュールリクエストからのモジュールタイプの手順に従って、moduleRequestを渡して実行した結果に設定します。
もしモジュールタイプの許可の手順をmoduleTypeとsettingsObjectに対して実行した結果がfalseであれば、onCompleteをnullを指定して実行し、終了します。
単一のモジュールスクリプトを取得するために、url、fetchClient、destination、options、settingsObject、referrer、moduleRequest、false、およびonCompleteを指定して実行します。もしperformFetchが与えられていた場合、それも渡します。
クラシックスクリプトを作成するには、 文字列 source、環境設定オブジェクト settings、URL baseURL、スクリプト取得オプション options、省略可能なブール値mutedErrors(デフォルトはfalse)、 および省略可能なURL-または-nullのsourceURLForWindowScripts(デフォルトはnull)を使用します:
mutedErrorsがtrueの場合、baseURLを
about:blankに設定します。
mutedErrorsがtrueの場合、baseURLはスクリプトの CORSクロスオリジンの レスポンスの URLであり、 JavaScriptに公開されるべきではありません。したがって、 baseURLはここでサニタイズされます。
settingsに対してスクリプトが無効化されている 場合、sourceを空の文字列に設定します。
scriptを新しいクラシックスクリプト として設定し、このアルゴリズムは後で初期化を行います。
scriptの設定オブジェクト をsettingsに設定します。
scriptのベースURL をbaseURLに設定します。
scriptの取得オプション をoptionsに設定します。
scriptのエラー抑制 をmutedErrorsに設定します。
scriptの解析エラーと 再スローされるエラー をnullに設定します。
クラシックスクリプト作成時間を記録する にはscriptとsourceURLForWindowScriptsを使用します。
resultをParseScript(source、 settingsのrealm、 script)に設定します。
ここでscriptを最後のパラメーターとして渡すことで、 resultの[[HostDefined]]がscriptになることを保証します。
resultがエラーのリストである場合、次の処理を行います:
scriptの解析エラーと 再スローされるエラー をresult[0]に設定します。
scriptを返します。
scriptの記録をresultに設定します。
scriptを返します。
JavaScriptモジュールスクリプトを作成するには、 文字列 source、環境設定オブジェクト settings、URL baseURL、および スクリプト取得オプション optionsを使用します:
settingsに対してスクリプトが無効化されている 場合、sourceを空の文字列に設定します。
scriptを新しいモジュールスクリプト として設定し、このアルゴリズムは後で初期化を行います。
scriptの設定オブジェクト をsettingsに設定します。
scriptのベースURLを baseURLに設定します。
scriptの取得オプション をoptionsに設定します。
scriptの解析エラーと 再スローされるエラー をnullに設定します。
resultをParseModule(source、 settingsのrealm、 script)に設定します。
ここでscriptを最後のパラメーターとして渡すことで、 resultの[[HostDefined]]がscriptになることを保証します。
resultがエラーのリストである場合、次の処理を行います:
scriptの解析エラー をresult[0]に設定します。
scriptを返します。
各モジュールリクエストレコード requestedについてresultの[[RequestedModules]]を処理します:
requestedの[[Attributes]]にレコードentryが含まれており、
そのentryの[[Key]]が"type"ではない場合:
新しいSyntaxError
例外を生成します。
scriptの解析エラー をerrorに設定します。
scriptを返します。
JavaScript仕様は、スクリプトの依存関係をロードする際にこの検証を再実行します。 無効な属性キーがある場合、モジュールグラフのロードは失敗するため、 ここでは不要な作業をスキップするために重複しています。 また、これは無効な静的インポートのエラーを動的インポートと一貫させるために、 無効な属性がHTMLに渡される前、したがってインポートされた指定子の検証前に報告されるようにします。
モジュール指定子を解決する にはscriptとrequestedの[[Specifier]]を使用し、 例外が発生した場合はキャッチします。
前のステップで例外が発生した場合、次の処理を行います:
scriptの解析エラー をその例外に設定します。
scriptを返します。
moduleTypeをモジュールリクエストからモジュールタイプを取得する ステップを実行してrequestedを処理します。
モジュールタイプを取得するステップを実行し、moduleTypeおよび settingsを指定してモジュールタイプが許可されているかどうか を確認し、falseであれば次の処理を行います:
このステップは、要求されたモジュール指定子とタイプ属性のすべてを検証しています。 解決不可能なモジュール指定子やサポートされていないタイプ属性を持つモジュールは、 解析できないものと同じように扱われます。 どちらの場合も、文法的な問題があるため、後でモジュールをリンクすることを検討することは不可能です。
scriptの記録をresultに設定します。
scriptを返します。
CSSモジュールスクリプトを作成するには、 文字列sourceと環境設定オブジェクト settingsを使用します:
scriptを新しいモジュールスクリプト として設定し、このアルゴリズムは後で初期化を行います。
scriptの設定オブジェクト をsettingsに設定します。
scriptの解析エラーと 再スローされるエラー をnullに設定します。
sheetを構築された
CSSStyleSheetを作成する手順を実行し、
引数として空の辞書を渡して、その結果をsheetに設定します。
sheetに対してCSSStyleSheetの規則を同期的に置き換える
手順を実行し、sourceを渡します。
これが例外を投げた場合、それをキャッチし、scriptの解析エラーをその例外に設定し、 scriptを返します。
CSSStyleSheetの規則を同期的に置き換える
手順は、sourceに@importルールが含まれている場合、例外を投げます。
これは現時点では設計によるもので、CSSモジュールスクリプトのこれらをどのように扱うかについて
合意がまだないため、合意が得られるまで完全にブロックされています。
scriptの記録を、 CreateDefaultExportSyntheticModule(sheet) の結果に設定します。
scriptを返します。
JSONモジュールスクリプトを作成するには、 文字列sourceと環境設定オブジェクト settingsを使用します:
scriptを新しいモジュールスクリプト として設定し、このアルゴリズムは後で初期化を行います。
scriptの設定オブジェクト をsettingsに設定します。
scriptの解析エラーと 再スローされるエラー をnullに設定します。
resultをParseJSONModule(source)に設定します。
これが例外を投げた場合、それをキャッチし、scriptの解析エラーをその例外に設定し、 scriptを返します。
scriptの記録をresultに設定します。
scriptを返します。
モジュールリクエストからモジュールタイプを取得するステップは、 モジュールリクエストレコード moduleRequestを与えられた場合、次の通りです:
moduleTypeを"javascript"に設定します。
moduleRequestの[[Attributes]]にレコードentryが含まれており、
そのentryの[[Key]]が"type"の場合、次の処理を行います:
entryの[[Value]]が"javascript"である場合、
moduleTypeをnullに設定します。
この仕様では、内部的に"javascript"モジュールタイプを
JavaScriptモジュールスクリプト
に使用するため、
モジュールが"javascript"タイプ属性を使用してインポートされるのを防ぐために
このステップが必要です(nullのmoduleTypeは、
モジュールタイプが許可されているかどうか
チェックで失敗する原因となります)。
それ以外の場合、moduleTypeをentryの[[Value]]に設定します。
moduleTypeを返します。
モジュールタイプが許可されているかどうかステップは、 文字列 moduleTypeと環境設定オブジェクト settingsを与えられた場合、次の通りです:
moduleTypeが"javascript"、"css"、または"json"でない場合、falseを返します。
moduleTypeが"css"であり、
CSSStyleSheet
インターフェースがsettingsの公開
されていない場合、falseを返します。
trueを返します。
モジュールタイプから取得先を決定するステップは、 デフォルト取得先 defaultDestinationと 文字列 moduleTypeを与えられた場合、次の通りです:
json"である場合、"json"を返します。
css"である場合、"style"を返します。
クラシックスクリプト script と省略可能なブール値rethrow errors(デフォルトはfalse)を与えられた場合、 クラシックスクリプトを実行する手順は以下の通りです:
settingsをscriptの設定オブジェクト に設定します。
スクリプトを実行できるか確認する にsettingsを使用します。これが「実行しない」を返した場合、 NormalCompletion(空)を返します。
クラシックスクリプトの実行開始時間を記録する にscriptを使用します。
スクリプトの実行準備をする にsettingsを使用します。
evaluationStatusをnullに設定します。
scriptの再スローされるエラー がnullでない場合、evaluationStatusをCompletion { [[Type]]: throw, [[Value]]: scriptの再スローされるエラー, [[Target]]: 空 }に設定します。
それ以外の場合、evaluationStatusをScriptEvaluation(scriptの 記録) に設定します。
ScriptEvaluation が完了しない場合、ユーザーエージェントが実行中のスクリプトを中止した ため、evaluationStatusはnullのままにします。
evaluationStatusが異常終了 である場合、次の処理を行います:
rethrow errorsがtrueで、scriptのエラー抑制 がfalseである場合、次の処理を行います:
スクリプト実行後のクリーンアップ をsettingsで行います。
evaluationStatus.[[Value]]を再スローします。
rethrow errorsがtrueで、scriptのエラー抑制 がtrueである場合、次の処理を行います:
スクリプト実行後のクリーンアップ をsettingsで行います。
"NetworkError"の
DOMException
をスローします。
それ以外の場合、rethrow errorsはfalseです。次のステップを実行します:
例外を報告する にevaluationStatus.[[Value]]を与え、 scriptの設定オブジェクト のグローバルオブジェクト に対して報告します。
スクリプト実行後のクリーンアップ をsettingsで行います。
evaluationStatusを返します。
スクリプト実行後のクリーンアップ をsettingsで行います。
evaluationStatusが正常終了である場合、evaluationStatusを返します。
ここに到達した場合、evaluationStatusはnullのままです。これはスクリプトが評価中に中断されたためです。
Completion { [[Type]]: throw, [[Value]]: 新しい
"QuotaExceededError"の
DOMExceptionを返します。
モジュールスクリプト script と省略可能なブール値preventErrorReporting(デフォルトはfalse)を与えられた場合、 モジュールスクリプトを実行する手順は以下の通りです:
settingsをscriptの設定オブジェクト に設定します。
スクリプトを実行できるか確認する にsettingsを使用します。これが「実行しない」を返した場合、 未定義を返すプロミス を返します。
モジュールスクリプトの実行開始時間を記録する にscriptを使用します。
スクリプトの実行準備をする にsettingsを使用します。
evaluationPromiseをnullに設定します。
scriptの再スローされるエラー がnullでない場合、evaluationPromiseを再スローされるエラーで拒否されたプロミス に設定します。
それ以外の場合:
recordをscriptの記録に設定します。
evaluationPromiseをrecord.Evaluate()に設定します。
このステップでは、モジュールのすべての依存関係が再帰的に評価されます。
もし、ユーザーエージェントが実行中のスクリプトを中止した結果としてEvaluateが完了しなかった場合、evaluationPromiseを新しい"QuotaExceededError" DOMExceptionで拒否されたプロミスに設定します。
preventErrorReportingがfalseである場合、evaluationPromiseが reasonで拒否された際に、例外を報告する にreasonを与え、scriptの設定オブジェクト のグローバルオブジェクト に対して報告します。
スクリプト実行後のクリーンアップ をsettingsで行います。
evaluationPromiseを返します。
環境設定オブジェクト settingsを使用して スクリプトを実行できるか確認する 手順は以下の通りです。これらは「実行」または「実行しない」のいずれかを返します。
settingsで指定されたグローバルオブジェクト
がWindowオブジェクトであり、
そのDocument
オブジェクトが完全にアクティブでない場合、「実行しない」を返します。
settingsに対してスクリプトが無効化されている 場合、「実行しない」を返します。
「実行」を返します。
環境設定オブジェクト settingsを使用して スクリプトの実行準備をする 手順は以下の通りです:
settingsのRealm実行コンテキスト をJavaScript実行コンテキストスタック にプッシュします。これが現在の実行中のJavaScript実行コンテキスト になります。
settingsを周囲のエージェント のイベントループ の現在実行中のタスク のスクリプト評価環境設定オブジェクトセット に追加します。
環境設定オブジェクト settingsを使用して スクリプト実行後のクリーンアップを行う 手順は以下の通りです:
アサート: settingsのRealm実行コンテキスト が現在の実行中のJavaScript実行コンテキスト であることを確認します。
settingsのRealm実行コンテキスト をJavaScript実行コンテキストスタック から削除します。
もしJavaScript実行コンテキストスタック が空になった場合、マイクロタスクチェックポイントを実行します。 (これがスクリプトを実行する場合、これらのアルゴリズムは再帰的に呼び出されます。)
これらのアルゴリズムは、1つのスクリプトが別のスクリプトを直接呼び出すことによってではなく、間接的に再帰的に呼び出される場合があります。例えば、スクリプトがイベントをディスパッチし、イベントリスナーが登録されている場合です。
実行中のスクリプトは、スクリプト の[[HostDefined]]フィールドにあるScriptOrModuleコンポーネントで、 実行中のJavaScript実行コンテキスト 内にあります。
JavaScriptの仕様にはこの可能性が考慮されていませんが、時には実行中のスクリプトを中止する必要があることがあります。これにより、ScriptEvaluationやソーステキストモジュールレコードのEvaluate呼び出しが直ちに停止し、JavaScript実行コンテキストスタック
が空になり、finallyブロックなどの通常のメカニズムがトリガーされません。
[JAVASCRIPT]
ユーザーエージェントは、スクリプトに対してCPUクォータ、メモリ制限、総実行時間制限、または帯域幅制限などのリソース制限を課すことがあります。スクリプトが制限を超えた場合、ユーザーエージェントは"QuotaExceededError"のDOMException
を投げるか、例外を発生させずにスクリプトを中止する
か、ユーザーにプロンプトを表示するか、スクリプトの実行をスロットルすることがあります。
例えば、次のスクリプトは決して終了しません。ユーザーエージェントは数秒待った後に、スクリプトを終了するか続行するかをユーザーに尋ねることができます。
< script >
while ( true ) { /* loop */ }
</ script >
ユーザーエージェントは、スクリプトによって(例えばwindow.alert()
APIを使用して)またはスクリプトの動作によって(例えば時間制限を超えたために)プロンプトが表示された場合に、スクリプトの無効化をユーザーに許可することが推奨されます。
スクリプトが実行中にスクリプトが無効化された場合、スクリプトは直ちに終了されるべきです。
ユーザーエージェントは、ブラウジングコンテキストを閉じる目的でスクリプトを特に無効にすることをユーザーに許可することがあります。
例えば、上記の例で述べたプロンプトでは、ユーザーにページ全体を閉じる機能を提供し、unloadイベントハンドラを実行しないようにすることもできます。
すべての現在のエンジンでサポートされています。
self.reportError(e)
指定された値eに対して、グローバルオブジェクトでerrorイベントを、未処理の例外と同じ方法でディスパッチします。
exceptionがJavaScript値である場合、そのエラー情報を抽出するには次の手順を行います:
attributesを、IDL属性でキーされた空のマップに設定します。
attributes[error]
をexceptionに設定します。
attributes[message],
attributes[filename],
attributes[lineno],
およびattributes[colno]
をexceptionから派生した実装依存の値に設定します。
ブラウザはここで指定されていない動作やJavaScript仕様に従って、通常のケースで役立つ値を収集するために動作を実装します(例えば、evalなど)。将来的には、これがより詳細に指定されるかもしれません。
attributesを返します。
exceptionがJavaScript値であり、特定のグローバルオブジェクト globalと、オプションのブール値omitError(デフォルトはfalse)に対して例外を報告するには次の手順を行います:
notHandledをtrueに設定します。
errorInfoをexceptionからエラー情報を抽出する結果に設定します。
scriptを、スクリプト内で実装依存の方法で見つけられるもの、またはnullに設定します。これは通常実行中のスクリプトであるべきです(特にクラシックスクリプトを実行する場合)。
実装は、エラーがミュートされるかどうかを判断するために使用されるスクリプトについて、あまり一般的でないケースにおいてもまだ互換性のある動作に達していません。
もしscriptがクラシックスクリプトであり、scriptのエラー抑制がtrueである場合、errorInfo[error]
をnullに、errorInfo[message]
を"Script error."に、errorInfo[filename]
を空の文字列に、errorInfo[lineno]
を0に、そしてerrorInfo[colno]
を0に設定します。
もしomitErrorがtrueである場合、errorInfo[error]
をnullに設定します。
もしglobalがエラーレポートモードでない場合、次の処理を行います:
もしglobalがEventTarget
を実装している場合、次の結果にnotHandledを設定します:
イベントをerror
という名前でglobalで発生させ、ErrorEventを使用し、
cancelable属性をtrueに初期化し、
追加の属性をerrorInfoに従って初期化します。
イベントハンドラーでtrueを返すと、イベントハンドラー処理アルゴリズムに従ってイベントがキャンセルされます。
globalのエラーレポートモード をfalseに設定します。
もしnotHandledがtrueである場合、次の処理を行います:
errorInfo[error]
をnullに設定します。
もしglobalがDedicatedWorkerGlobalScope
を実装している場合、グローバルタスクをキューに入れるをDOM操作タスクソースで行い、
globalに関連付けられたWorkerの関連するグローバルオブジェクト
に対して次のステップを実行します:
workerObjectをWorker
オブジェクトに設定します。
これはglobalに関連付けられています。
notHandledをイベントを発生させる結果に設定します。
これはerror
という名前でworkerObjectに対して発生させ、
ErrorEvent
を使用し、cancelable属性をtrueに初期化し、
追加の属性をerrorInfoに従って初期化します。
もしnotHandledがtrueである場合、次の処理を行います。 例外を報告する にはworkerObjectの関連するグローバルオブジェクト に対してomitErrorをtrueに設定して行います。
実際のexception値は所有者のレルムで利用できませんが、ユーザーエージェントは、メッセージ、ファイル名、その他の属性を設定するのに十分な情報を引き続き保持し、開発者コンソールに報告する可能性もあります。
それ以外の場合、ユーザーエージェントはexceptionを開発者コンソールに報告することができます。
もしワーカーとそのWorkerオブジェクトを接続している暗黙のポートが切断された場合(つまり、親ワーカーが終了された場合)、ユーザーエージェントはそのWorkerオブジェクトにerrorイベントハンドラーがないかのように、
またそのワーカーのonerror
属性がnullであるかのように振る舞わなければなりませんが、それ以外は上記のように振る舞わなければなりません。
したがって、エラーレポートは、専用ワーカーの連鎖に沿って、元のドキュメントまで伝播します。たとえこの連鎖の途中でいくつかのワーカーが終了され、ガベージコレクトされたとしても。
この標準の以前の改訂版では、例外を報告するアルゴリズムが定義されていました。issue #958の一環として、これが例外を報告するに置き換えられ、異なる入力を受け取り、異なる動作をします。issue #10516は、仕様エコシステムの更新を追跡しています。
reportError(e)メソッドの手順は、
例外を報告する
eを
thisに対して実行します。
ここでエラー抑制が適用されるかどうかは不明です。ChromeとSafariでは抑制されていますが、Firefoxでは抑制されていません。issue #958も参照してください。
すべての現在のエンジンでサポートされています。
ErrorEventインターフェイスは以下のように定義されています:
[Exposed=*]
interface ErrorEvent : Event {
constructor (DOMString type , optional ErrorEventInit eventInitDict = {});
readonly attribute DOMString message ;
readonly attribute USVString filename ;
readonly attribute unsigned long lineno ;
readonly attribute unsigned long colno ;
readonly attribute any error ;
};
dictionary ErrorEventInit : EventInit {
DOMString message = "";
USVString filename = "";
unsigned long lineno = 0;
unsigned long colno = 0;
any error ;
};
message
属性は、初期化された値を返さなければなりません。これはエラーメッセージを表します。
filename
属性は、初期化された値を返さなければなりません。これは、エラーが最初に発生したスクリプトのURLを表します。
lineno
属性は、初期化された値を返さなければなりません。これはスクリプト内でエラーが発生した行番号を表します。
colno
属性は、初期化された値を返さなければなりません。これはスクリプト内でエラーが発生した列番号を表します。
error
属性は、初期化された値を返さなければなりません。これは初期的にはundefinedに初期化されなければなりません。適切な場合には、エラーを表すオブジェクトに設定されます(例えば、キャッチされない例外の場合の例外オブジェクトなど)。
すべての現在のエンジンでサポートされています。
同期的な実行時スクリプトエラーに加えて、スクリプトは非同期のPromiseの拒否を経験することがあります。これはunhandledrejection
およびrejectionhandled
イベントによって追跡されます。これらの拒否の追跡はHostPromiseRejectionTracker
抽象操作によって行われますが、その報告はここで定義されています。
グローバルオブジェクト globalに対して拒否されたPromiseについて通知するには:
listをglobalのクローンとする通知が予定されている拒否されたPromiseリストとします。
もしlistが空である ならば、 戻ります。
空にする globalの通知が予定されている拒否されたPromiseリスト。
グローバルタスクをキューに入れる globalを与えて、DOM操作タスクソースに実行する次のステップを設定します:
各Promisepをlistの中で行う:
もしpの[[PromiseIsHandled]]がtrueならば、続行する。
notCanceledを次の結果にする:イベントを発生させることを、unhandledrejection
という名前でglobalに対して行い、PromiseRejectionEvent
を使用し、キャンセル可能
属性をtrueに初期化し、promise
属性をpに初期化し、reason
属性をpの[[PromiseResult]]に初期化します。
もしnotCanceledがtrueであれば、ユーザーエージェントは pの[[PromiseResult]]を開発者コンソールに報告することがあります。
もしpの[[PromiseIsHandled]]がfalseであるならば、追加する pをglobalの未解決の拒否されたPromiseウィークセットに追加します。
すべての現在のエンジンでサポートされています。
PromiseRejectionEvent
インターフェイスは以下のように定義されています:
[Exposed=*]
interface PromiseRejectionEvent : Event {
constructor (DOMString type , PromiseRejectionEventInit eventInitDict );
readonly attribute object promise ;
readonly attribute any reason ;
};
dictionary PromiseRejectionEventInit : EventInit {
必須 object promise ;
any reason ;
};
すべての現在のエンジンでサポートされています。
promise
属性は、初期化された値を返さなければなりません。これは、この通知に関するPromiseを表します。
Web
IDLの変換ルールによるPromise<T>
型は常に入力を新しいPromiseにラップするため、promise
属性はobject
型となっており、元のPromiseオブジェクトへの不透明なハンドルを表すのに適しています。
すべての現在のエンジンでサポートされています。
reason
属性は、初期化された値を返さなければなりません。これは、Promiseの拒否理由を表します。
インポートマップ解析結果は、構造体で、スクリプトに似ており、またscript
要素の結果に格納することができますが、
他の目的のためにスクリプトとしてカウントされません。
以下の項目を持ちます:
inputという文字列とbaseURLというURLを与えて、 インポートマップの解析結果を作成するには:
resultをインポートマップ解析結果 とし、そのインポートマップをnullに、 再スローされるエラーをnullにします。
inputおよびbaseURLを指定して、インポートマップ文字列を解析する、例外をキャッチし、 例外が発生した場合はresultの再スローされるエラー にその例外を設定します。そうでない場合は、 resultのインポートマップに返された値を設定します。
resultを返します。
Window globalおよび
インポートマップ解析結果
resultを指定してインポートマップを登録するには:
もしresultの再スローされるエラーが nullでない場合、globalに対してresultの再スローされるエラーを指定して例外を報告し、 終了します。
確認: globalのインポートマップは空のインポートマップである。
モジュール指定子を解決するアルゴリズムは、 モジュール指定子文字列をURLに変換するための主要なエントリポイントです。 インポートマップが関与していない場合、 これは比較的簡単であり、URLに似たモジュール指定子を解決するに還元されます。
非空のインポートマップが存在する場合、 動作はより複雑になります。これは、すべての適用可能なモジュール指定子マップから、最も具体的なものから最も一般的なものへ、 スコープに基づいて候補エントリを確認し、 最上位のスコープされていないインポートにフォールバックし、 最も具体的なプレフィックスから最も一般的なプレフィックスへと進みます。各候補について、インポートの一致を解決するアルゴリズムが次の結果を返します:
指定子をURLに正常に解決します。その場合、モジュール指定子を解決するアルゴリズムはそのURLを返します。
例外をスローします。その場合、モジュール指定子を解決するアルゴリズムはその例外を再スローし、他のフォールバックは行いません。
エラーなしで解決に失敗します。この場合、外側のモジュール指定子を解決するアルゴリズムは次の候補に進みます。
最終的に、候補となるいずれのモジュール指定子マップでも成功しなかった場合、モジュール指定子を解決するは例外をスローします。 したがって、結果は常にURLかスローされた例外のいずれかです。
モジュール指定子を解決するには、スクリプト-または-nullなreferringScriptと、 文字列のspecifierを指定します:
settingsObjectとbaseURLをnullに設定します。
もしreferringScriptがnullでない場合、次の操作を行います:
そうでない場合:
settingsObjectを現在の設定オブジェクトに設定します。
baseURLをsettingsObjectのAPIベースURLに設定します。
importMapを空のインポートマップに設定します。
もしsettingsObjectのグローバルオブジェクトがWindowを実装している場合、
importMapをsettingsObjectのグローバルオブジェクトの
インポートマップに設定します。
baseURLStringをbaseURLのシリアライズ結果に設定します。
asURLをspecifierとbaseURLを指定してURLに似たモジュール指定子を解決する結果に設定します。
normalizedSpecifierをasURLがnullでない場合はそのシリアライズ結果に、 それ以外の場合はspecifierに設定します。
各 scopePrefix → scopeImportsをimportMapのスコープから取得して繰り返し処理を行います:
もしscopePrefixがbaseURLStringであるか、scopePrefixがU+002F (/)で終わり、 かつscopePrefixがbaseURLStringのコードユニットプレフィックスである場合、次の操作を行います:
scopeImportsMatchをnormalizedSpecifier、asURL、およびscopeImportsを指定してインポートの一致を解決する結果に設定します。
もしscopeImportsMatchがnullでない場合、それを返します。
topLevelImportsMatchをnormalizedSpecifier、asURL、およびimportMapのインポートを指定してインポートの一致を解決する結果に設定します。
もしtopLevelImportsMatchがnullでない場合、それを返します。
この時点で、specifierはimportMapによって再マッピングされませんでしたが、URLに変換できた可能性があります。
もしasURLがnullでない場合、それを返します。
TypeErrorをスローし、
specifierが裸の指定子であったが、importMapによって何も再マッピングされなかったことを示します。
インポートの一致を解決するには、文字列のnormalizedSpecifier、URL-または-nullなasURL、およびモジュール指定子マップのspecifierMapを指定します:
各 specifierKey → resolutionResultをspecifierMapから取得して繰り返し処理を行います:
もしspecifierKeyがnormalizedSpecifierである場合、次の操作を行います:
もしresolutionResultがnullである場合、TypeErrorをスローし、specifierKeyの解決がnullエントリによってブロックされたことを示します。
これにより、モジュール指定子を解決するアルゴリズム全体が終了し、他のフォールバックは行われません。
resolutionResultを返します。
次のすべてが真である場合:
specifierKeyがU+002F (/)で終わる;
specifierKeyがnormalizedSpecifierのコードユニットプレフィックスである; および
asURLがnullであるか、またはasURLが特別である;
場合、次の操作を行います:
もしresolutionResultがnullである場合、TypeErrorをスローし、specifierKeyの解決がnullエントリによってブロックされたことを示します。
これにより、モジュール指定子を解決するアルゴリズム全体が終了し、他のフォールバックは行われません。
normalizedSpecifierの先頭のspecifierKeyプレフィックスの後の部分をafterPrefixとします。
urlを、resolutionResultでafterPrefixを指定してURL解析した結果に設定します。
もしurlが失敗した場合、TypeErrorをスローし、normalizedSpecifierの解決がafterPrefix部分をspecifierKeyプレフィックスに対して相対的にURL解析できなかったためにブロックされたことを示します。
これにより、モジュール指定子を解決するアルゴリズム全体が終了し、他のフォールバックは行われません。
もしシリアライズされたresolutionResultがコードユニットプレフィックスではない場合、urlがシリアライズされ、
normalizedSpecifierの解決がspecifierKeyプレフィックスより上位にバックトラッキングしたためにブロックされたことを示す
TypeErrorをスローします。
これにより、モジュール指定子を解決するアルゴリズム全体が終了し、他のフォールバックは行われません。
urlを返します。
nullを返します。
モジュール指定子を解決するアルゴリズムは、可能であれば、より一般的なスコープまたは「imports」にフォールバックします。
URLに似たモジュール指定子を解決するには、文字列のspecifierと、URLのbaseURLを指定します:
もしspecifierが「/」「./」または「../」で始まる場合、次の操作を行います:
urlをbaseURLを指定してspecifierのURL解析結果に設定します。
もしurlが失敗した場合、nullを返します。
このようなケースの一例として、specifierが「../foo」で、baseURLがdata:URLである場合があります。
urlを返します。
これには、specifierが「//」で始まる場合も含まれます。したがって、urlは、baseURLとは異なるホストを持つことになるかもしれません。
urlを(ベースURLなしで)specifierのURL解析結果に設定します。
もしurlが失敗した場合、nullを返します。
urlを返します。
インポートマップは、モジュール識別子の解決を制御するための機能です。インポートマップは、script要素のtype属性を「importmap」に設定し、その子テキスト内容にインポートマップのJSON表現を含めることで提供されます。
各Documentには、1つのインポートマップしか処理されません。最初のインポートマップが読み込まれた後、他のインポートマップは無視され、それに対応するscript要素はerrorイベントを生成します。同様に、import()式やscript要素のtype属性が「module」に設定された場合、以降のインポートマップは無視されます。
これらの制限や外部インポートマップのサポートがないのは、機能の初期バージョンをシンプルに保つためです。時間の経過とともに、実装者の帯域幅が許す限り、これらの制限は解除される可能性があります。
インポートマップの最も単純な使い方は、裸のモジュール識別子をグローバルにリマップすることです。
{
"imports" : {
"moment" : "/node_modules/moment/src/moment.js"
}
}
これにより、import moment from "moment";という文が機能し、/node_modules/moment/src/moment.jsのJavaScriptモジュールを取得して評価します。
インポートマップは、トレーリングスラッシュを使用して、モジュール識別子のクラスをURLのクラスにリマップすることができます。
{
"imports" : {
"moment/" : "/node_modules/moment/src/"
}
これにより、import localeData from "moment/locale/zh-cn.js";という文が機能し、/node_modules/moment/src/locale/zh-cn.jsのJavaScriptモジュールを取得して評価します。このようなトレーリングスラッシュのマッピングは、裸の識別子のマッピングとよく組み合わせて使用されます。
{
"imports" : {
"moment" : "/node_modules/moment/src/moment.js" ,
"moment/" : "/node_modules/moment/src/"
}
これにより、「moment」で指定された「メインモジュール」と、「moment/locale/zh-cn.js」などのパスで指定された「サブモジュール」の両方が利用可能になります。
インポートマップがリマップできるモジュール識別子は、ベア識別子だけではありません。
"URLに似た"識別子、すなわち絶対URLとして解析可能なもの、または "/"、"./"、"../" で始まるものも
リマップすることができます:
{
"imports" : {
"https://cdn.example.com/vue/dist/vue.runtime.esm.js" : "/node_modules/vue/dist/vue.runtime.esm.js" ,
"/js/app.mjs" : "/js/app-8e0d62a03.mjs" ,
"../helpers/" : "https://cdn.example/helpers/"
}
}
リマップされるURLと、リマップされるURLの両方が、絶対URLとして指定できるだけでなく、"/"、"./"、"../"
で始まる相対URLとしても指定できることに注意してください。(これらの始まりのシンボルがない相対URLとしては指定できません。これらのシンボルは、ベアモジュール識別子と区別するのに役立ちます。)また、末尾のスラッシュマッピングがこの文脈でも動作することにも注意してください。
このようなリマッピングは、正規化後のURLに基づいて動作し、インポートマップキーとインポートされたモジュール識別子に指定された文字列の一致は必要ありません。したがって、例えばこのインポートマップがhttps://example.com/app.htmlに含まれている場合、import "/js/app.mjs"がリマップされるだけでなく、import "./js/app.mjs"やimport "./foo/../js/app.mjs"もリマップされます。
以前のすべての例は、インポートマップのトップレベル "imports" キーを使用して、グローバルにモジュール識別子をリマップしていました。トップレベルの
"scopes" キーは、参照元のモジュールが特定のURLプレフィックスと一致する場合にのみ適用される、ローカライズされたリマッピングを提供するために使用できます。例えば:
{
"scopes" : {
"/a/" : {
"moment" : "/node_modules/moment/src/moment.js"
},
"/b/" : {
"moment" : "https://cdn.example.com/moment/src/moment.js"
}
}
}
このインポートマップでは、import "moment"の意味は、ステートメントを含む参照スクリプトによって異なります:
/a/下にあるスクリプト内では、/node_modules/moment/src/moment.jsをインポートします。
/b/下にあるスクリプト内では、https://cdn.example.com/moment/src/moment.jsをインポートします。
/c/下にあるスクリプト内では、解決に失敗し、例外がスローされます。
スコープの典型的な使用法は、ウェブアプリケーション内で「同じ」モジュールの複数のバージョンが存在し、モジュールグラフの一部が一方のバージョンをインポートし、他の部分が別のバージョンをインポートすることを許可することです。
スコープは互いに重なり合い、グローバル "imports" 識別子マップとも重なることができます。解決時には、最も特定的なものから最も一般的なものの順にスコープが参照されます。特定性は、コードユニットが少ない演算によってスコープを並べ替えて測定されます。したがって、例えば"/scope2/scope3/"は"/scope2/"よりも特定的であり、これはトップレベル(スコープなし)のマッピングよりも特定的と見なされます。
次のインポートマップはこれを示しています:
{
"imports" : {
"a" : "/a-1.mjs" ,
"b" : "/b-1.mjs" ,
"c" : "/c-1.mjs"
},
"scopes" : {
"/scope2/" : {
"a" : "/a-2.mjs"
},
"/scope2/scope3/" : {
"b" : "/b-3.mjs"
}
}
}
これにより、次のような解決が行われます(簡潔さのために相対URLを使用しています):
| 識別子 | ||||
|---|---|---|---|---|
"a"
| "b"
| "c"
| ||
| 参照元 | /scope1/r.mjs
| /a-1.mjs
| /b-1.mjs
| /c-1.mjs
|
/scope2/r.mjs
| /a-2.mjs
| /b-1.mjs
| /c-1.mjs
| |
/scope2/scope3/r.mjs
| /a-2.mjs
| /b-3.mjs
| /c-1.mjs
| |
インポートマップは、サブリソースインテグリティチェックで使用されるモジュールに対してインテグリティメタデータを提供するためにも使用できます。[SRI]
次のインポートマップはこれを示しています:
{
"imports" : {
"a" : "/a-1.mjs" ,
"b" : "/b-1.mjs" ,
"c" : "/c-1.mjs"
},
"integrity" : {
"/a-1.mjs" : "sha384-Li9vy3DqF8tnTXuiaAJuML3ky+er10rcgNR/VqsVpcw+ThHmYcwiB1pbOxEbzJr7" ,
"/d-1.mjs" : "sha384-MBO5IDfYaE6c6Aao94oZrIOiC6CGiSN2n4QUbHNPhzk5Xhm0djZLQqTpL0HzTUxk"
}
}
上記の例は、モジュール/a-1.mjsと/d-1.mjsに対してインテグリティメタデータを提供し、後者がインポートマップ内でインポートとして定義されていなくても適用されます。
子テキストコンテンツを持つscript要素は、
インポートマップを表すものであり、
次のインポートマップの作成要件に一致しなければなりません:
有効なJSONでなければなりません。[JSON]
JSONはJSONオブジェクトを表している必要があり、最大で"imports"、
"scopes"、および"integrity"の3つのキーを持つことができます。
存在する場合、"imports"、"scopes"、および"integrity"キーに対応する値は、それぞれがJSONオブジェクトである必要があります。
"imports"キーに対応する値は、存在する場合、有効なモジュール識別子マップでなければなりません。
"scopes"キーに対応する値は、存在する場合、有効なURL文字列であるキーを持つJSONオブジェクトでなければならず、その値は有効なモジュール識別子マップでなければなりません。
"integrity"キーに対応する値は、存在する場合、有効なURL文字列であるキーを持つJSONオブジェクトでなければならず、その値はインテグリティ属性の要件に適合する必要があります。
有効なモジュール識別子マップは、次の要件を満たすJSONオブジェクトです:
すべてのキーは空であってはならない。
すべての値は文字列でなければならない。
各値は、有効な絶対URLまたは、"/"、"./"、または"../"で始まる有効なURL文字列のいずれかでなければならない。
特定のキーが"/"で終わる場合、対応する値も同様に終わらなければならない。
imports、モジュール識別子マップ;
scopes、順序付きマップ の URLからモジュール識別子マップへの変換; そして
integrity、モジュールインテグリティマップ。
モジュール識別子マップは、順序付きマップであり、そのキーは文字列であり、その値はURLまたはnullです。
モジュールインテグリティマップは、順序付きマップであり、そのキーはURLであり、その値は文字列であり、インテグリティメタデータとして使用されます。
空のインポートマップとは、そのインポートマップにおいて、importsとscopesが 両方とも空のマップであるものを指します。
各Windowは、インポートマップを持ち、
初期状態では空のインポートマップです。
各Windowは、インポートマップが許可されるかというブール値を持ち、初期状態ではtrueです。
環境設定オブジェクトに対して今後のインポートマップを禁止するには、settingsObjectを指定して次の手順を行います:
globalをsettingsObjectのグローバルオブジェクトに設定します。
もしglobalがWindowを実装していない場合は、
処理を終了します。
globalのインポートマップが許可されるかをfalseに設定します。
現在、インポートマップはモジュールの読み込みが開始された後、またはインポートマップが1つでもロードされた時点で禁止されています。これらの制限は、将来の仕様の改訂で解除される可能性があります。
文字列 inputとURL baseURLが与えられたときに、インポートマップ文字列を解析するには、
parsedを、JSON文字列をInfra値に解析する 結果として設定します。inputを与えられます。
もしparsedが順序付きマップでない場合、
次のエラーをスローします。
TypeError
トップレベルの値がJSONオブジェクトである必要があることを示します。
sortedAndNormalizedImportsを空の順序付きマップとして設定します。
もしparsed["imports"]が存在する場合、
次の手順を実行します:
もしparsed["imports"]が順序付きマップでない場合、次のエラーをスローします。TypeError
"imports"トップレベルキーの値がJSONオブジェクトである必要があることを示します。
sortedAndNormalizedImportsをモジュール識別子マップのソートと正規化の結果に設定します。
parsed["imports"]および
baseURLを与えられます。
sortedAndNormalizedScopesを空の順序付きマップとして設定します。
もしparsed["scopes"]が存在する場合、
次の手順を実行します:
もしparsed["scopes"]が順序付きマップでない場合、次のエラーをスローします。TypeError
"scopes"トップレベルキーの値がJSONオブジェクトである必要があることを示します。
sortedAndNormalizedScopesをスコープのソートと正規化の結果に設定します。parsed["scopes"]および
baseURLを与えられます。
normalizedIntegrityを空の順序付きマップとして設定します。
もしparsed["integrity"]が存在する場合、
次の手順を実行します:
もしparsed["integrity"]が順序付きマップでない場合、次のエラーをスローします。TypeError
"integrity"トップレベルキーの値がJSONオブジェクトである必要があることを示します。
normalizedIntegrityをモジュールインテグリティマップの正規化の結果に設定します。parsed["integrity"]および
baseURLを与えられます。
もしparsedのキーが、"imports"、
"scopes"、または"integrity"以外の項目を含む場合、ユーザーエージェントは、コンソールに警告を報告する必要があります。
インポートマップに無効なトップレベルキーが含まれていたことを示します。
これにより、タイプミスを検出するのに役立ちます。エラーではありません。エラーであれば、将来的な拡張が後方互換性を持たせて追加されることを妨げるからです。
次のインポートマップを返します:インポートマップ そのimportsは sortedAndNormalizedImportsであり、 scopesは sortedAndNormalizedScopesであり、そのintegrityは normalizedIntegrityです。
このインポートマップが
この解析アルゴリズムによって生成されるものは、非常に正規化されています。
例えば、https://example.com/base/page.htmlを基準URLとした場合、入力は
{
"imports" : {
"/app/helper" : "node_modules/helper/index.mjs" ,
"lodash" : "/node_modules/lodash-es/lodash.js"
}
}
«[
"https://example.com/app/helper" → https://example.com/base/node_modules/helper/index.mjs
"lodash" → https://example.com/node_modules/lodash-es/lodash.js
]»
モジュール識別子マップのソートと正規化には、順序付きマップであるoriginalMapとURL baseURLが与えられた場合:
normalizedを空の順序付きマップとして設定します。
各 specifierKey → valueの originalMapの項目を処理します。
normalizedSpecifierKeyを識別子キーの正規化の結果に設定します。specifierKeyおよびbaseURLが与えられます。
もしnormalizedSpecifierKeyがnullの場合は、続行します。
もしvalueが文字列でない場合、次の手順を行います:
ユーザーエージェントはコンソールに警告を報告 し、アドレスが文字列である必要があることを示すことができます。
normalized[normalizedSpecifierKey]をnullに設定します。
続行します。
addressURLをURLに似たモジュール識別子の解決の結果に設定します。valueおよびbaseURLが与えられます。
もしaddressURLがnullの場合、次の手順を行います:
ユーザーエージェントはコンソールに警告を報告 し、そのアドレスが無効であったことを示すことができます。
normalized[normalizedSpecifierKey]をnullに設定します。
続行します。
もしspecifierKeyがU+002F (/)で終わり、シリアライゼーションのaddressURL が U+002F (/)で終わらない場合、次の手順を行います:
ユーザーエージェントはコンソールに警告を報告 し、 その識別子キーspecifierKeyに対して無効なアドレスが指定されたことを示すことができます。specifierKeyがスラッシュで終わるため、アドレスもスラッシュで終わる必要があります。
normalized[normalizedSpecifierKey]をnullに設定します。
続行します。
normalized[normalizedSpecifierKey]をaddressURLに設定します。
降順でソートされたnormalizedを返します。エントリaがエントリbより小さい場合、aのキーがコードユニットが少ない順にbのキーより小さい場合。
スコープをソートして正規化するには、 順序付きマップ originalMapとURL baseURLが与えられた場合:
normalizedを空の順序付きマップとして設定します。
各 scopePrefix → potentialSpecifierMapのoriginalMapを処理します:
もしpotentialSpecifierMapが順序付きマップでない場合、次のエラーをスローします。
TypeError
scopePrefixで指定されたスコープの値がJSONオブジェクトである必要があることを示します。
scopePrefixURLをURL パースのscopePrefixおよびbaseURLの結果として設定します。
もしscopePrefixURLが失敗した場合、次の手順を行います:
ユーザーエージェントは、コンソールに警告を報告し、 スコーププレフィックスのURLが解析できなかったことを示すことができます。
続行します。
normalizedScopePrefixをURLのシリアライゼーションのscopePrefixURLの結果として設定します。
normalized[normalizedScopePrefix]を モジュール識別子マップのソートと正規化の結果として設定します。potentialSpecifierMapおよびbaseURLを与えられます。
normalizedを降順でソートした結果を返します。エントリaがエントリbより小さい場合、aのキーがコードユニットが少ない順にbのキーより小さい場合。
上記の2つのアルゴリズムでは、キーとスコープを降順にソートすることで、"foo/bar/"が"foo/"の前に来ます。これにより、モジュール識別子の解決時に"foo/bar/"が"foo/"より高い優先順位を持つことになります。
モジュールインテグリティマップを正規化するには、 順序付きマップ originalMapが与えられた場合:
normalizedを空の順序付きマップとして設定します。
各 key → valueのoriginalMapを処理します:
resolvedURLをURLに似たモジュール識別子の解決の結果として設定します。keyおよびbaseURLが与えられます。
「imports」とは異なり、インテグリティマップのキーはモジュール識別子ではなくURLとして扱われます。ただし、「URLに似たモジュール識別子の解決」アルゴリズムを使用して、モジュール識別子と誤解される可能性のあるfooのような「ベア」相対URLを禁止します。
もしresolvedURLがnullの場合、次の手順を行います:
ユーザーエージェントは、コンソールに警告を報告 し、キーの解決に失敗したことを示すことができます。
続行します。
もしvalueが文字列でない場合、次の手順を行います:
ユーザーエージェントは、コンソールに警告を報告 し、インテグリティメタデータ の値は文字列でなければならないことを示すことができます。
続行します。
normalized[resolvedURL]をvalueに設定します。
normalizedを返します。
識別子キーを正規化するには、 文字列 specifierKeyとURL baseURLが与えられた場合:
もしspecifierKeyが空文字列である場合、次の手順を行います:
ユーザーエージェントは、コンソールに警告を報告 し、識別子キーが空文字列であってはならないことを示すことができます。
nullを返します。
urlをURLに似たモジュール識別子の解決の結果として設定します。specifierKeyおよびbaseURLが与えられます。
もしurlがnullでない場合、そのURLのシリアライゼーションを返します。
specifierKeyを返します。
JavaScriptの仕様には、ホスト環境に応じて異なる実装依存の抽象操作がいくつか含まれています。このセクションでは、ユーザーエージェントホストのためにそれらを定義します。
JavaScriptには、実装依存のHostEnsureCanAddPrivateElement(O) という抽象操作が含まれています。ユーザーエージェントは次の実装を使用する必要があります。[JAVASCRIPT]
もしOがWindowProxy
オブジェクトである場合、または実装が
Location
を含む場合、次の結果を返します: Completion { [[Type]]: throw, [[Value]]: 新しい
TypeError
}。
NormalCompletion(未使用)を返します。
JavaScriptのプライベートフィールドは任意のオブジェクトに適用できます。これは、特にエキゾチックなホストオブジェクトに対する実装を非常に複雑にする可能性があるため、JavaScript言語仕様はこのフックを提供して、ホストがホスト定義の基準を満たすオブジェクトに対してプライベートフィールドを拒否できるようにしています。HTMLの場合、WindowProxy
および
Location
は特にナビゲーションやセキュリティに関して複雑なセマンティクスを持っているため、プライベートフィールドセマンティクスの実装が困難であるため、私たちの実装では単にこれらのオブジェクトを拒否しています。
JavaScriptには、実装依存のHostEnsureCanCompileStringsという抽象操作が含まれており、Dynamic Code Brand Checks提案によって再定義されています。ユーザーエージェントは次の実装を使用する必要があります。[JAVASCRIPT] [JSDYNAMICCODEBRANDCHECKS]
? EnsureCSPDoesNotBlockStringCompilation(realm, parameterStrings, bodyString, codeString, compilationType, parameterArgs, bodyArg)を実行します。 [CSP]
Dynamic Code Brand Checks提案には、 実装依存のHostGetCodeForEval(argument)という抽象操作が含まれています。 ユーザーエージェントは次の実装を使用する必要があります。[JSDYNAMICCODEBRANDCHECKS]
もしargumentがTrustedScript
オブジェクトである場合、argumentのデータを返します。
それ以外の場合は、コードを返しません。
JavaScriptには、実装依存のHostPromiseRejectionTracker(promise, operation)という抽象操作が含まれています。ユーザーエージェントは次の実装を使用する必要があります。 [JAVASCRIPT]
scriptを実行中のスクリプトとして設定します。
もしscriptがクラシックスクリプト であり、scriptのエラーがミュートされている場合は、処理を終了します。
settingsObjectを現在の設定オブジェクトとして設定します。
もしscriptがnullでない場合、settingsObjectをscriptの設定オブジェクトに設定します。
globalをsettingsObjectのグローバルオブジェクトとして設定します。
もしoperationが"reject"の場合、次の手順を行います:
promiseをglobalの通知予定の拒否されたプロミスリストに追加します。
もしoperationが"handle"の場合、次の手順を行います:
もしglobalの通知予定の拒否されたプロミスリストがpromiseを含む場合、そのリストからpromiseを削除し、処理を終了します。
もしglobalの未処理の拒否されたプロミスの弱集合がpromiseを含まない場合、処理を終了します。
promiseをglobalの未処理の拒否されたプロミスの弱集合から削除します。
globalに対してイベントを発火するために、グローバルタスクをキューに追加します。イベント名はrejectionhandled
で、PromiseRejectionEvent
を使用し、promise
属性をpromiseで初期化し、reason
属性をpromiseの[[PromiseResult]]で初期化します。
Temporal提案には、実装依存のHostSystemUTCEpochNanosecondsという抽象操作が含まれています。 ユーザーエージェントは次の実装を使用する必要があります。[JSTEMPORAL]
settingsObjectをglobalの関連する設定オブジェクトとして設定します。
timeをsettingsObjectの現在の壁時計時刻として設定します。
nsをUnix エポックからtimeまでのナノ秒数として設定し、最も近い整数に丸めます。
nsをclampingして、nsMinInstantとnsMaxInstantの間に収めた結果を返します。
Reference/Global_Objects/Promise#Incumbent_settings_object_tracking
1つのエンジンのみでサポートされています。
JavaScript仕様は、ホストによってスケジュールされ、後で実行されるジョブおよび、ジョブの一部として呼び出されるJavaScript関数をカプセル化するJobCallback
Recordsを定義しています。JavaScript仕様には、ジョブがどのようにスケジュールされるか、JobCallbacksがどのように処理されるかをホストが定義できる多くの実装依存抽象操作が含まれています。HTMLはこれらの抽象操作を使用して、Promise内のインカンベント設定オブジェクトおよびFinalizationRegistryのコールバックを追跡するために、JobCallbacks内のインカンベント設定オブジェクトおよびJavaScript実行コンテキストを保存および復元します。このセクションでは、ユーザーエージェントホストのためにそれらを定義します。
JavaScriptには、実装依存のHostCallJobCallback(callback, V, argumentsList)という抽象操作が含まれており、ホストがタスク内からJavaScriptコールバックを呼び出す際に状態を復元できるようにしています。ユーザーエージェントは次の実装を使用する必要があります: [JAVASCRIPT]
incumbent settingsをcallback.[[HostDefined]].[[IncumbentSettings]]として設定します。
script execution contextをcallback.[[HostDefined]].[[ActiveScriptContext]]として設定します。
コールバックを実行する準備をする際にincumbent settingsを使用します。
これは、コールバックが実行されている間に、現職の概念に影響を与えます。
もしscript execution contextがnullでない場合、JavaScript実行コンテキストスタックにscript execution contextをプッシュします。
これは、コールバックが実行されている間に、アクティブスクリプトに影響を与えます。
resultをCall(callback.[[Callback]], V, argumentsList)の結果として設定します。
もしscript execution contextがnullでない場合、JavaScript実行コンテキストスタックからscript execution contextをポップします。
コールバック実行後のクリーンアップをincumbent settingsを使用して行います。
resultを返します。
JavaScriptには、FinalizationRegistryオブジェクトにオブジェクトを登録し、それらがガベージコレクションされた場合にクリーンアップアクションをスケジュールする機能があります。JavaScript仕様には、実装依存のHostEnqueueFinalizationRegistryCleanupJob(finalizationRegistry)という抽象操作が含まれており、クリーンアップアクションをスケジュールします。
クリーンアップ作業のタイミングと発生は、JavaScript仕様内で実装依存です。ユーザーエージェントは、オブジェクトがガベージコレクションされる時期や、WeakRef.prototype.deref()メソッドの戻り値が未定義かどうか、FinalizationRegistryのクリーンアップコールバックが発生するかどうかに影響を与える可能性があります。人気のあるウェブブラウザでは、JavaScriptでアクセスできないオブジェクトが、ガベージコレクタによって無期限に保持されるというよく知られたケースがあります。HTMLは、マイクロタスクチェックポイントの実行アルゴリズムで、WeakRefオブジェクトをクリアします。作成者は、ガベージコレクション実装のタイミングの詳細に依存しない方が良いでしょう。
クリーンアップアクションは、同期的なJavaScriptの実行と交互には行われず、キューに追加されたタスク内で実行されます。ユーザーエージェントは次の実装を使用する必要があります: [JAVASCRIPT]
globalをfinalizationRegistry.[[Realm]]のグローバルオブジェクトとして設定します。
globalに対して次の手順を実行するために、JavaScriptエンジンタスクソースにグローバルタスクをキューに追加します。
entryをfinalizationRegistry.[[CleanupCallback]].[[Callback]].[[Realm]]の環境設定オブジェクトとして設定します。
entryでスクリプトを実行できるかどうか確認します。これが「実行しない」を返した場合、処理を終了します。
entryでスクリプトを実行する準備をします。
これは、クリーンアップコールバックが実行されている間に、entryの概念に影響を与えます。
resultをfinalizationRegistryのCleanupFinalizationRegistryを実行した結果として設定します。
entryを使用してスクリプト実行後のクリーンアップを行います。
もしresultが急な完了である場合、globalに対してresult.[[Value]]で与えられた例外を報告します。
JavaScriptには、特定のレルム内で汎用ジョブを実行するための実装依存のHostEnqueueGenericJob(job,
realm)という抽象操作が含まれています(例: Atomics.waitAsyncから生じるPromiseを解決するためのジョブ)。
ユーザーエージェントは次の実装を使用する必要があります:
[JAVASCRIPT]
globalをrealmのグローバルオブジェクトとして設定します。
globalに対してjob()を実行するために、グローバルタスクをキューに追加します。
JavaScriptには、Promise関連の操作をスケジュールするための実装依存のHostEnqueuePromiseJob(job, realm)という抽象操作が含まれています。HTMLはこれらの操作をマイクロタスクキューにスケジュールします。ユーザーエージェントは次の実装を使用する必要があります: [JAVASCRIPT]
もしrealmがnullでない場合、job settingsをrealmの設定オブジェクトとして設定します。それ以外の場合、job settingsをnullとして設定します。
もしrealmがnullでない場合、それは実行される著者コードのレルムです。jobがNewPromiseReactionJobによって返される場合、それはPromiseのハンドラ関数のレルムです。jobがNewPromiseResolveThenableJobによって返される場合、それはthen関数のレルムです。
もしrealmがnullである場合、著者コードが実行されないか、または著者コードが必ず例外を投げることが保証されます。前者の場合、著者が実行するコードを渡さなかった可能性があり、例えばpromise.then(null, null)のようなケースです。後者の場合、それは取り消されたProxyが渡されたためです。いずれの場合も、以下のステップでjob
settingsが使用されるべきステップがスキップされます。
NewPromiseResolveThenableJobとNewPromiseReactionJobは、取り消されたプロキシの場合に非nullレルム(現在のレルムレコード)を提供するようです。前述のテキストはそれを反映するように更新される可能性があります。
job()を実行するために、マイクロタスクをキューに追加します。
もしjob settingsがnullでない場合、スクリプトを実行できるかどうか確認します。これが「実行しない」を返した場合、処理を終了します。
もしjob settingsがnullでない場合、スクリプトを実行する準備をします。
これは、ジョブが実行される間、entryの概念に影響を与えます。
resultをjob()の結果として設定します。
jobは、抽象クロージャであり、NewPromiseReactionJobまたはNewPromiseResolveThenableJobによって返されます。jobがNewPromiseReactionJobによって返される場合、Promiseのハンドラ関数、およびjobがNewPromiseResolveThenableJobによって返される場合、then関数はJobCallback
Records内にラップされます。HTMLは現職の設定オブジェクトおよびJavaScript実行コンテキストをHostMakeJobCallback内で保存し、HostCallJobCallback内でそれらを復元します。
もしjob settingsがnullでない場合、スクリプト実行後のクリーンアップを行います。
もしresultが急な完了である場合、realmのグローバルオブジェクトに対して、result.[[Value]]によって与えられた例外を報告します。
HostEnqueuePromiseJobがnullレルム(例: Promise.prototype.thenがnullハンドラで呼び出された場合)で呼び出されるが、ジョブが急に終了する場合(Promise capabilityのresolveまたはrejectハンドラが例外をスローしたため、その後、このクラスが供給された関数をラップしてからPromiseスーパークラスコンストラクタに渡す)、どのグローバルが使用されるかについては非常に難しいケースがあります。この場合、現在のレルムが各ステップで異なる可能性があります(別のレルムからPromiseコンストラクタまたはPromise.prototype.thenを使用する場合)。このような場合、どのグローバルが使用されるかについては、issue #10526を参照してください。
JavaScriptには、タイムアウト後に実行される操作をスケジュールするための実装依存のHostEnqueueTimeoutJob(job, milliseconds)という抽象操作が含まれています。HTMLはこれらの操作をタイムアウト後のステップの実行を使用してスケジュールします。 ユーザーエージェントは次の実装を使用する必要があります: [JAVASCRIPT]
globalをrealmのグローバルオブジェクトとして設定します。
timeoutStepを、globalに対してjob()を実行するためにグローバルタスクをキューに追加するアルゴリズムステップとして設定します。
global、「JavaScript」、milliseconds、およびtimeoutStepを与えて、タイムアウト後のステップを実行します。
JavaScriptには、実装依存のHostMakeJobCallback(callable)という抽象操作が含まれており、 ホストがタスク内から呼び出されるJavaScriptコールバックに状態を付与できるようにします。ユーザーエージェントは次の実装を使用する必要があります: [JAVASCRIPT]
incumbent settingsを現職の設定オブジェクトとして設定します。
active scriptをアクティブスクリプトとして設定します。
script execution contextをnullとして設定します。
もしactive scriptがnullでない場合、新しいJavaScript実行コンテキストを設定し、 そのFunctionフィールドをnullに、Realmフィールドをactive scriptの設定オブジェクトのレルムに、ScriptOrModuleをactive scriptの記録に設定します。
以下に示すように、これはジョブコールバックが呼び出されるときに現在のアクティブスクリプトを伝播するために使用されます。
active scriptがnullでなく、この方法で保存することが有用であるケースは以下のとおりです:
Promise. resolve( 'import(`./example.mjs`)' ). then( eval);
このステップがなければ(およびHostCallJobCallbackでそれを使用するステップがなければ)、
import()式が評価されるときにアクティブスクリプトは存在しないでしょう、
なぜならeval()は特定のスクリプトに由来しない組み込み関数だからです。
このステップがあることで、アクティブスクリプトは上記のコードからジョブに伝播され、import()が元のスクリプトのベースURLを適切に使用できるようになります。
ユーザーが以下のボタンをクリックすると、active scriptはnullになります:
< button onclick = "Promise.resolve('import(`./example.mjs`)').then(eval)" > Click me</ button >
この場合、イベントハンドラーのJavaScript関数はイベントハンドラーの現在の値を取得するアルゴリズムによって作成され、 null [[ScriptOrModule]]値を持つ関数が作成されます。そのため、Promiseの機構がHostMakeJobCallbackを呼び出すとき、 アクティブスクリプトを渡すことはできません。
その結果、import()式が評価されるときにアクティブスクリプトは依然として存在しないでしょう。幸いなことに、これはHostLoadImportedModuleの実装によって処理されており、
現在の設定オブジェクトのAPIベースURLを使用することで対処されています。
JobCallback Record { [[Callback]]: callable, [[HostDefined]]: { [[IncumbentSettings]]: incumbent settings, [[ActiveScriptContext]]: script execution context } }を返します。
JavaScript仕様は、モジュールの構文とその処理モデルのホストに依存しない部分を定義しています。本仕様は、その処理モデルの残りの部分、すなわち、script要素のtype属性を"module"に設定してモジュールシステムをブートストラップし、モジュールがどのようにフェッチされ、解決され、実行されるかを定義しています。[JAVASCRIPT]
JavaScript仕様では「スクリプト」と「モジュール」を区別している一方で、一般的に本仕様では従来のスクリプトとモジュールスクリプトという用語が使われています。両方ともscript要素を使用するためです。
modulePromise = import(specifier)
specifierで識別されるモジュールスクリプトのモジュール名前空間オブジェクトに対するPromiseを返します。これにより、import文形式を使用せずに、実行時にモジュールスクリプトを動的にインポートすることができます。specifierはアクティブスクリプトに相対的に解決されます。
無効なspecifierが与えられた場合、またはモジュールグラフのフェッチまたは評価中にエラーが発生した場合、返されたPromiseは拒否されます。
この構文は、従来のスクリプトとモジュールスクリプトの両方で使用できます。したがって、従来のスクリプトの世界からモジュールスクリプトの世界への橋渡しを提供します。
url = import.meta.url
アクティブなモジュールスクリプトのベースURLを返します。
この構文はモジュールスクリプト内でのみ使用できます。
url = import.meta.resolve(specifier)
specifierを返します。それはアクティブスクリプトに相対的に解決されます。つまり、これはimport(specifier)を使用してインポートされるURLを返します。
無効なspecifierが与えられた場合、TypeError例外をスローします。
この構文はモジュールスクリプト内でのみ使用できます。
モジュールマップは、マップであり、タプルでキー指定されています。URLレコードと文字列から成るタプルです。URLレコードはモジュールがフェッチされたリクエストURLであり、文字列はモジュールのタイプ(例: "javascript")を示します。モジュールマップの値は、モジュールスクリプト、null(フェッチ失敗を表す)、またはプレースホルダー値
"fetching"のいずれかです。モジュールマップは、インポートされたモジュールスクリプトがドキュメントやワーカーごとに一度だけフェッチ、解析、評価されることを保証するために使用されます。
モジュールマップが(URL、モジュールタイプ)でキー指定されるため、次のコードはモジュールマップに3つの個別のエントリを作成します。これは、"javascript"タイプで3つの異なる(URL、モジュールタイプ)タプルが生成されるためです。
import "https://example.com/module.mjs" ;
import "https://example.com/module.mjs#map-buster" ;
import "https://example.com/module.mjs?debug=true" ;
つまり、URLクエリやフラグメントを変化させることで、モジュールマップ内に別々のエントリを作成できます。これらは無視されません。そのため、3つの個別のフェッチと3つの個別のモジュール評価が実行されます。
対照的に、次のコードはモジュールマップに1つのエントリしか作成しません。これらの入力にURLパーサーを適用した後、生成されるURLレコードが等しいからです。
import "https://example.com/module2.mjs" ;
import "https:example.com/module2.mjs" ;
import "https://///example.com\\module2.mjs" ;
import "https://example.com/foo/../module2.mjs" ;
したがって、この2つ目の例では、1つのフェッチと1つのモジュール評価のみが行われます。
この動作は共有ワーカーが解析されたコンストラクターURLによってキー指定される方法と同じです。
モジュールタイプもモジュールマップのキーの一部であるため、次のコードはモジュールマップに2つの個別のエントリを作成します(最初のタイプは"javascript"、2つ目のタイプは"css"です)。
< script type = module >
import "https://example.com/module" ;
</ script >
< script type = module >
import "https://example.com/module" with { type: "css" };
</ script >
これにより、2つの個別のフェッチと2つの個別のモジュール評価が行われる可能性があります。
実際には、まだ仕様が定まっていないメモリキャッシュ(問題#6110を参照)のため、リソースはWebKitやBlinkベースのブラウザでは1度だけフェッチされる場合があります。また、すべてのモジュールタイプが互いに排他的である限り、単一のモジュールスクリプトのフェッチでモジュールタイプチェックが少なくとも1つのインポートに失敗するため、最大で1つのモジュール評価が行われます。
モジュールマップのキーにタイプを含める目的は、誤ったタイプ属性を持つインポートが、正しいタイプを持つ同じspecifierの別のインポートの成功を妨げないようにすることです。
JavaScriptモジュールスクリプトは、他のJavaScriptモジュールからインポートする際のデフォルトのインポートタイプです。つまり、import文にtypeインポート属性が欠けている場合、インポートされたモジュールスクリプトのタイプはJavaScriptになります。typeインポート属性を持つimport文を使用してJavaScriptリソースをインポートしようとすると失敗します。
< script type = "module" >
// 次のすべてのインポートは失敗します。インポートされる.mjsファイルがJavaScript MIMEタイプで提供されていると仮定しています。
// JavaScriptモジュールスクリプトはデフォルトであり、インポートタイプ属性を使用してインポートすることはできません。
import foo from "./foo.mjs" with { type: "javascript" };
import foo2 from "./foo2.mjs" with { type: "js" };
import foo3 from "./foo3.mjs" with { type: "" };
await import ( "./foo4.mjs" , { with : { type: null } });
await import ( "./foo5.mjs" , { with : { type: undefined } });
</ script >
Reference/Operators/import.meta/resolve
すべての現在のエンジンでサポートされています。
Reference/Operators/import.meta
すべての現在のエンジンでサポートされています。
JavaScriptには、実装依存のHostGetImportMetaProperties抽象操作が含まれています。 ユーザーエージェントは、次の実装を使用する必要があります:[JAVASCRIPT]
moduleScriptをmoduleRecord.[[HostDefined]]とする。
確認:moduleScriptの基本URLがnullでないことを確認する。moduleScriptはJavaScriptモジュールスクリプトであるため。
以下の手順をspecifier引数に対して実行する:
specifierを? ToString(specifier)に設定する。
moduleScriptおよびspecifierを使用して、モジュール指定子を解決した結果をurlに設定する。
urlのシリアライズを返す。
stepsを使用して、! CreateBuiltinFunction(steps, 1,
"resolve", « ») をresolveFunctionに設定する。
« レコード
{ [[Key]]: "url",
[[Value]]: urlString }, レコード
{ [[Key]]: "resolve", [[Value]]:
resolveFunction }
»を返す。
インポート属性提案には、実装依存 のHostGetSupportedImportAttributes 抽象操作が含まれています。ユーザーエージェントは次の実装を使用する必要があります: [JSIMPORTATTRIBUTES]
« "type" » を返します。
JavaScriptには、実装依存のHostLoadImportedModule抽象操作が含まれています。 ユーザーエージェントは次の実装を使用する必要があります:[JAVASCRIPT]
settingsObjectを現在の設定オブジェクトに設定します。
もしsettingsObjectのグローバルオブジェクトがWorkletGlobalScope
またはServiceWorkerGlobalScopeを実装しており、loadStateが未定義の場合:
loadStateが未定義の場合、それは現在のフェッチ処理が動的なimport()
呼び出しによって開始されたことを意味します。これは直接的であるか、動的にインポートされたモジュールの推移的依存関係をロードする際に発生します。
completionを完了レコード { [[Type]]: throw,
[[Value]]: 新しいTypeError,
[[Target]]: empty }に設定します。
FinishLoadingImportedModule(referrer, moduleRequest, payload, completion)を実行します。
Returnします。
referencingScriptをnullに設定します。
originalFetchOptionsをデフォルトのクラシックスクリプトフェッチオプションに設定します。
fetchReferrerを"client"に設定します。
もしreferrerがスクリプトレコード またはモジュールレコードの場合:
referencingScriptをreferrer.[[HostDefined]]に設定します。
settingsObjectをreferencingScriptの設定オブジェクトに設定します。
fetchReferrerをreferencingScriptの基本URLに設定します。
originalFetchOptionsをreferencingScriptのフェッチオプションに設定します。
referrerは通常、スクリプトレコード またはモジュールレコードですが、イベントハンドラの場合はそうではありません。これはイベントハンドラの現在の値を取得するアルゴリズムに従います。例えば、以下の場合:
< button onclick = "import('./foo.mjs')" > Click me</ button >
もしclick
イベントが発生した場合、import()
式が実行される時点で、GetActiveScriptOrModuleはnullを返し、この操作はフォールバックとして現在のレルムをreferrerとして受け取ります。
さらにインポートマップを禁止し、settingsObjectに設定します。
urlをreferencingScriptとmoduleRequest.[[Specifier]]に基づいてモジュール識別子を解決する結果として設定し、例外をキャッチします。もし例外が発生した場合、resolutionErrorをスローされた例外として設定します。
もし前のステップで例外が発生した場合:
completionを完了レコード { [[Type]]: throw, [[Value]]: resolutionError, [[Target]]: empty }に設定します。
FinishLoadingImportedModule(referrer, moduleRequest, payload, completion)を実行します。
Returnします。
fetchOptionsを子孫スクリプトフェッチオプションを取得する結果として、originalFetchOptions、url、およびsettingsObjectを使用して設定します。
destinationを"script"に設定します。
fetchClientをsettingsObjectに設定します。
もしloadStateが未定義でない場合:
destinationをloadState.[[Destination]]に設定します。
fetchClientをloadState.[[FetchClient]]に設定します。
単一のインポートされたモジュールスクリプトをフェッチするをurl、fetchClient、destination、fetchOptions、settingsObject、fetchReferrer、moduleRequest、および以下に定義されているonSingleFetchCompleteとして渡して実行します。もしloadStateが未定義でなく、かつloadState.[[PerformFetch]]がnullでない場合、loadState.[[PerformFetch]]も一緒に渡します。
onSingleFetchCompleteは、moduleScriptが与えられた場合に以下のアルゴリズムを実行します:
completionをnullに設定します。
もしmoduleScriptがnullの場合、completionを完了レコード { [[Type]]: throw,
[[Value]]: 新しいTypeError,
[[Target]]: empty }に設定します。
それ以外の場合、もしmoduleScriptの構文エラーがnullでない場合:
それ以外の場合、completionを完了レコード { [[Type]]: normal, [[Value]]: moduleScriptのレコード, [[Target]]: empty }に設定します。
FinishLoadingImportedModule(referrer, moduleRequest, payload, completion)を実行します。
イベント、ユーザーインタラクション、スクリプト、レンダリング、ネットワーキングなどを調整するために、ユーザーエージェントはこのセクションで説明されているように、イベントループを使用しなければなりません。各エージェントには、そのエージェントに固有のイベントループが関連付けられています。
イベントループは、同一オリジンのウィンドウエージェントの場合、「ウィンドウイベントループ」として知られています。イベントループは、専用ワーカーエージェント、共有ワーカーエージェント、またはサービスワーカーエージェントの場合、「ワーカーイベントループ」として知られています。また、イベントループは、ワークレットエージェントの場合、「ワークレットイベントループ」として知られています。
イベントループは必ずしも実装スレッドに対応しているわけではありません。例えば、複数のウィンドウイベントループが1つのスレッドで協力的にスケジュールされることもあります。
ただし、[[CanBlock]]がtrueに設定されている様々なワーカーエージェントについては、JavaScript仕様書はそれらに関して前進の進捗に関する要件を課しており、事実上、これらの場合にはエージェントごとに専用のスレッドが必要になります。
イベントループには1つ以上のタスクキューがあります。タスクキューは、セットのタスクです。
タスクキューは、セットであり、キューではありません。なぜなら、イベントループ処理モデルは選択されたキューから最初の実行可能なタスクを取得するため、最初のタスクをデキューするわけではないからです。
マイクロタスクキューはタスクキューではありません。
タスクは、次のような作業を担当するアルゴリズムをカプセル化します:
特定のイベントオブジェクトを特定のイベントターゲットオブジェクトにディスパッチすることは、専用のタスクによって行われることがよくあります。
すべてのイベントがタスクキューを使用してディスパッチされるわけではなく、多くは他のタスク中にディスパッチされます。
HTMLパーサーが1バイト以上をトークナイズし、その後のトークンを処理することは、通常タスクとして行われます。
コールバックの呼び出しは、専用のタスクによって行われることがよくあります。
アルゴリズムがリソースを取得するとき、非ブロッキングで取得が行われる場合は、リソースの一部または全部が利用可能になった後の処理がタスクによって実行されます。
一部の要素にはDOM操作に反応してトリガーされるタスクがあります。例えば、その要素がドキュメントに挿入されたときなどです。
形式的には、タスクは、次の項目を持つ構造体です:
Document、またはウィンドウイベントループにないタスクの場合はnull。
タスクは、そのドキュメントがnullであるか、完全にアクティブである場合、「実行可能」です。
それぞれのタスクは、ソースフィールドに基づき、特定のタスクソースから来ると定義されています。各イベントループに対して、すべてのタスクソースは、特定のタスクキューに関連付けられなければなりません。
要するに、タスクソースは標準の中で論理的に異なるタイプのタスクを区別するために使用され、ユーザーエージェントがそれらを区別したい場合があります。タスクキューは、ユーザーエージェントが特定のイベントループ内でタスクソースを統合するために使用します。
例えば、ユーザーエージェントがマウスおよびキーイベント用のタスクキューを1つ持ち、他のすべてのタスクソースに関連付けられた別のキューを持っているとします。次に、イベントループ処理モデルの初期ステップで与えられた自由度を使用して、インターフェースを応答性の高い状態に保ちながら、他のタスクキューを犠牲にしないようにするため、キーボードおよびマウスイベントに他のタスクよりも3/4の優先度を与えることができます。このセットアップでも、処理モデルはユーザーエージェントが1つのタスクソースからのイベントを順不同で処理することがないように強制します。
各イベントループには現在実行中のタスクがあり、これはタスクまたはnullです。初期状態ではnullです。これは再入性を処理するために使用されます。
各イベントループにはマイクロタスクキューがあり、これはキューです。初期状態では空のマイクロタスクのキューです。マイクロタスクとは、マイクロタスクをキューに追加アルゴリズムを使用して作成されたタスクを指す口語的な表現です。
各イベントループにはマイクロタスクチェックポイントを実行中というブール値があり、初期状態ではfalseです。これはマイクロタスクチェックポイントを実行するアルゴリズムの再入呼び出しを防ぐために使用されます。
各ウィンドウイベントループには、初期状態でゼロに設定されたDOMHighResTimeStamp
最後のレンダー機会時間があります。
各ウィンドウイベントループには、初期状態でゼロに設定されたDOMHighResTimeStamp
最後のアイドル期間開始時間があります。
ウィンドウイベントループ loopの同じループのウィンドウを取得するには、その関連するエージェントのイベントループがloopであるすべてのWindowオブジェクトを返します。
sourceというタスクソースに、stepsという一連のステップを実行するタスクをキューに追加するには、オプションでevent loopおよびdocumentを指定します:
event loopが指定されていない場合、event loopを暗黙のイベントループに設定します。
documentが指定されていない場合、documentを暗黙のドキュメントに設定します。
taskを新しいタスクとして作成します。
taskのstepsをstepsに設定します。
taskのsourceをsourceに設定します。
taskのdocumentをdocumentに設定します。
taskのスクリプト評価環境設定オブジェクトセットを空のセットに設定します。
queueを、sourceがevent loopに関連付けられているタスクキューに設定します。
taskをqueueに追加します。
タスクをキューに追加する際にイベントループやドキュメントを渡さない場合、曖昧で仕様が不明瞭な暗黙のイベントループや暗黙のドキュメントの概念に依存することになります。仕様の著者は、これらの値を常に渡すか、代わりにグローバルタスクをキューに追加するまたは要素タスクをキューに追加するといったラッパーアルゴリズムを使用するべきです。ラッパーアルゴリズムの使用が推奨されます。
sourceというタスクソースに、globalというグローバルオブジェクトとstepsという一連のステップを使用してグローバルタスクをキューに追加するには:
event loopをglobalの関連するエージェントのイベントループに設定します。
documentを、globalがWindowオブジェクトである場合、globalの関連付けられたDocumentに設定します。それ以外の場合はnullに設定します。
source、event loop、document、およびstepsを指定してタスクをキューに追加します。
sourceというタスクソースに、elementという要素とstepsという一連のステップを使用して要素タスクをキューに追加するには:
globalをelementの関連するグローバルオブジェクトに設定します。
source、global、およびstepsを指定してグローバルタスクをキューに追加します。
マイクロタスクをキューに追加するには、stepsという一連のステップを実行し、オプションでdocumentを指定します:
Assert: 周囲のエージェントが存在することを確認します。つまり、このアルゴリズムは並行して呼び出されることはありません。
documentが指定されていない場合、documentを暗黙のドキュメントに設定します。
microtaskを新しいタスクとして作成します。
microtaskのstepsをstepsに設定します。
microtaskのsourceをマイクロタスクソースに設定します。
microtaskのdocumentをdocumentに設定します。
microtaskのスクリプト評価環境設定オブジェクトセットを空のセットに設定します。
microtaskをeventLoopのマイクロタスクキューにエンキューします。
マイクロタスクが実行中にイベントループをスピンすると、マイクロタスクが通常のタスクキューに移動されることがあります。これは、マイクロタスクのソース、ドキュメント、およびスクリプト評価環境設定オブジェクトセットが参照される唯一のケースであり、マイクロタスクチェックポイントを実行するアルゴリズムでは無視されます。
暗黙のイベントループは、タスクをキューに追加する際に呼び出しアルゴリズムのコンテキストから推定されるイベントループです。これは通常、曖昧ではありません。なぜなら、大多数の仕様アルゴリズムは単一のエージェント(したがって単一のイベントループ)のみを含むからです。例外は、ウィンドウとワーカー間の通信のようなエージェント間通信を含むまたは指定するアルゴリズムであり、そのようなケースでは暗黙のイベントループの概念に依存してはならず、仕様はタスクをキューに追加する際に明示的にイベントループを指定する必要があります。
event loopというイベントループにタスクをキューに追加する際の暗黙のドキュメントは、次のように決定されます:
event loopがウィンドウイベントループでない場合は、nullを返します。
タスクが要素のコンテキストでキューに追加されている場合は、要素のノードドキュメントを返します。
タスクがブラウジングコンテキストのコンテキストでキューに追加されている場合は、ブラウジングコンテキストのアクティブドキュメントを返します。
タスクがスクリプトによって、またはそのためにキューに追加されている場合は、スクリプトの設定オブジェクトのグローバルオブジェクトの関連付けられたDocumentを返します。
Assert: このステップには決して到達しません。なぜなら、前の条件のいずれかが真であるからです。本当に?
暗黙のイベントループと暗黙のドキュメントは、漠然と定義されており、遠隔操作的な側面が多くあります。これらを、特に暗黙のドキュメントを削除することが望まれています。詳しくは、issue #4980を参照してください。
イベントループは、存在する限り、以下の手順を継続的に実行しなければなりません。
oldestTask と taskStartTime を null に設定します。
もし、イベントループに、少なくとも1つの タスクキューがあり、少なくとも1つの 実行可能な タスクがある場合は、以下の手順を実行します。
taskQueue をそのような タスクキュー の1つに設定します。この選択は 実装依存の方法で行われます。
マイクロタスクキューは タスクキューではないことを思い出してください。したがって、この手順で選択されることはありません。ただし、タスクキューに関連付けられたマイクロタスクソースが選択される場合があります。その場合、次のステップで選択されたタスクは、元々はマイクロタスクでしたが、イベントループをスピンするの一環として移動されました。
taskStartTime を安全でない共有現在時刻に設定します。
oldestTask を taskQueue の最初の 実行可能な タスク に設定し、taskQueue から 削除します。
もし、oldestTask のドキュメントが null でない場合、taskStartTimeと oldestTask のドキュメントを使って タスクの開始時刻を記録します。
oldestTask の手順を実行します。
taskEndTime を 安全でない共有現在時刻 に設定します。 [HRT]
もし、oldestTask が null でない場合は、次の手順を実行します。
top-level browsing contexts を空の セットに設定します。
各 環境設定オブジェクトについて oldestTask の スクリプト評価環境設定オブジェクトセットの settings を実行します。
global を settings の グローバルオブジェクトに設定します。
もし、global のブラウジングコンテキストが null である場合は、 続行します。
tlbc を global の ブラウジングコンテキストの トップレベルブラウジングコンテキストに設定します。
もし、tlbc が null でない場合は、それをに追加します top-level browsing contextsに。
長時間のタスクを報告する、taskStartTime, taskEndTime, top-level browsing contexts, および oldestTask を指定します。
もし、oldestTask のドキュメントが null でない場合、taskEndTime と oldestTask のドキュメントを使って タスク終了時刻を記録します。
もし、これは ウィンドウイベントループで、この イベントループに タスクキューに実行可能な実行可能な タスクが1つもない場合、次の手順を実行します。
このイベントループの 最後のアイドル期間の開始時刻 を安全でない共有現在時刻に設定します。
computeDeadline を次の手順に設定します。
deadline をこのイベントループの最後のアイドル期間の開始時刻に50を加えたものに設定します。
50msの上限は、新しいユーザー入力に対する応答性を人間の知覚の閾値内で確保するためです。
hasPendingRenders を false に設定します。
このイベントループに対する同一ループウィンドウの各 windowInSameLoop について、
もし windowInSameLoop の アニメーションフレームコールバックのリストが 空でないか、ユーザーエージェントが windowInSameLoop に保留中のレンダリング更新があると信じる場合、hasPendingRenders を true に設定します。
timerCallbackEstimates を マップから値を取得する結果に設定します。 windowInSameLoopのアクティブなタイマーのマップの。
timerCallbackEstimatesの各timeoutDeadlineについて、 timeoutDeadlineがdeadlineよりも小さい場合は、deadlineをtimeoutDeadlineに設定します。
もし、hasPendingRendersが true の場合、次の手順を実行します。
nextRenderDeadline をこのイベントループの最後のレンダー機会の時刻に(現在のリフレッシュレートで1000を割った値)を加えたものに設定します。
リフレッシュレートはハードウェアまたは実装固有である可能性があります。リフレッシュレートが60Hzの場合、nextRenderDeadlineは 最後のレンダー機会の時刻の約16.67ms後になります。
もし、nextRenderDeadline が deadline よりも小さい場合は、 nextRenderDeadline を返します。
deadline を返します。
このイベントループの各同一ループウィンドウについて、次のステップを実行して、winのアイドル期間の開始アルゴリズムを実行します: winの関連設定オブジェクトのクロスオリジン隔離機能を考慮して、computeDeadlineを呼び出した結果を返します。[REQUESTIDLECALLBACK]
もし、これが ワーカイベントループの場合は、次の手順を実行します。
もしこのイベントループのエージェントの単一の領域のグローバルオブジェクトが
サポートされている
DedicatedWorkerGlobalScopeであり、ユーザーエージェントがその時点でレンダリングの更新が有益であると信じている場合は、次の手順を実行します。
now を 現在の高解像度時刻 に設定します
DedicatedWorkerGlobalScopeの場合。
[HRT]
アニメーションフレームコールバックを実行します
そのDedicatedWorkerGlobalScopeに対して、nowをタイムスタンプとして渡します。
その専用ワーカーのレンダリングを現在の状態を反映するように更新します。
レンダリングの更新に関する注記と同様に、ウィンドウイベントループ内で、ユーザーエージェントは専用ワーカー内のレンダリングの速度を決定できます。
もし、タスクが1つもない場合、
イベントループのタスクキューにおいて、
WorkerGlobalScopeオブジェクトのクローズフラグがtrueである場合は、イベントループを破棄し、
これらの手順を中止して、次の手順に進みます。ワーカーを実行する手順は、以下のWebワーカーセクションに記載されています。
ウィンドウイベントループ eventLoopは、存在する限り、以下の手順を並行して実行しなければなりません。
少なくとも1つのナビゲーブルが、その アクティブなドキュメントの関連エージェントのイベントループがeventLoopであり、 レンダリングの機会を持つ可能性があるまで待ちます。
eventLoop の 最後のレンダー機会の時刻 を 安全でない共有現在時刻に設定します。
各 navigable に レンダリングの機会がある場合、次の手順を実行します。 グローバルタスクをキューに入れる レンダリングタスクソースで、 navigable の アクティブなウィンドウを与え、 レンダリングを更新する。
これは、レンダリングの更新を冗長に呼び出す原因になるかもしれません。しかし、これらの呼び出しは、不必要なレンダリングステップに従って、観察可能な効果を持たないでしょう。実装は、すでにキューに入っていない場合にのみこのタスクをキューに入れるなどの最適化を導入できます。ただし、タスクに関連付けられたドキュメントがタスクの処理前に非アクティブになる可能性があることに注意してください。
frameTimestamp を eventLoop の 最後のレンダー機会の時刻に設定します。
docs を、すべての 完全にアクティブな Document
オブジェクトに設定します。その 関連エージェント のイベントループが
eventLoopであり、以下の条件を満たす限り、任意にソートされます。
その Document
Bのコンテナドキュメントが
Aの場合は、リスト内のAの後に表示される必要があります。
同じコンテナドキュメント Cを持つ2つのドキュメントAとBがある場合は、リスト内のAとBの順序は、それぞれのシャドウインクルードツリー順に従って配置される必要があります。
以下の手順で docs を繰り返し処理する際、各 Document
はリストで見つけた順序で処理される必要があります。
非レンダリング可能ドキュメントのフィルタリング: 以下のいずれかが真である場合、docsからDocumentオブジェクトdocを削除します。
doc が レンダーブロックされている場合。
doc の可視状態が
"hidden" である場合。
doc のレンダリングがビュー遷移のために抑制されている場合。
いくつかのイベントループを共有するドキュメントが同時にレンダリングの機会を持たない可能性があるため、並行手順で確認することに加えて、ここでもレンダリングの機会を確認する必要があります。
不要なレンダリング: 以下のすべてが真である場合、docsからDocumentオブジェクトdocを削除します。
ユーザーエージェントが、docのナビゲーブルノードのレンダリングを更新しても目に見える効果がないと信じている場合。
docのアニメーションフレームコールバックのリストが空である場合。
ユーザーエージェントが他の理由でレンダリングの更新をスキップする方が好ましいと信じるDocumentオブジェクトをすべてdocsから削除します。
非レンダリング可能ドキュメントのフィルタリング手順は、ユーザーエージェントがユーザーに新しいコンテンツを表示できない場合に、レンダリングの更新を防ぎます。
不要なレンダリング手順は、新しいコンテンツを描画する必要がない場合にレンダリングの更新を防ぎます。
この手順は、以下の手順が他の理由で実行されるのを防ぐことをユーザーエージェントに許可します。例えば、特定のタスクを、マイクロタスクチェックポイントのみを挟んで(例:アニメーションフレームコールバックを挟まずに)すぐに実行することを保証するためです。具体的には、ユーザーエージェントは、タイマーコールバックを一緒にまとめて、途中のレンダリング更新を行わないようにすることが望ましい場合があります。
各docのリビールを行います。
各docの自動フォーカス候補のフラッシュを実行します。もしそのナビゲーブルノードがトップレベルトラバーサブルである場合。
各docのリサイズ手順を実行します。 docに対して。[CSSOMVIEW]
各docのスクロール手順を実行します。 docに対して。[CSSOMVIEW]
各docのメディアクエリの評価と変更の報告を実行します。docに対して。[CSSOMVIEW]
各docのアニメーションの更新とイベントの送信を実行します。docに対して、相対的な高解像度時刻とframeTimestampおよびdocの関連するグローバルオブジェクトをタイムスタンプとして渡します。
各docのフルスクリーン手順を実行します。docに対して。[FULLSCREEN]
各 doc が docs に対して、ユーザーエージェントが CanvasRenderingContext2D
または OffscreenCanvasRenderingContext2D
に関連付けられたバックストレージが失われていることを検出した場合、その各 context に対して コンテキスト損失手順 を実行しなければなりません。
canvas を context のキャンバス属性の値に設定します。もしcontextがCanvasRenderingContext2Dの場合。そうでない場合は、関連するOffscreenCanvasオブジェクトに設定します。
context の コンテキストロストを true に設定します。
レンダリングコンテキストをデフォルトの状態にリセットします。contextを指定して。
shouldRestoreを、イベントを発火する結果に設定します。イベント名はcontextlost、canvasに対して、キャンセル可能属性が
true に初期化されます。
もしshouldRestoreがfalseの場合、これらの手順を中止します。
contextの属性を使用してバックストレージを作成し、それをcontextに関連付けることでcontextを復元しようとします。これが失敗した場合、これらの手順を中止します。
context の コンテキストロストを false に設定します。
イベントを発火するします。イベント名はcontextrestored、canvasに対して。
各docのアニメーションフレームコールバックを実行します。docに対して、相対的な高解像度時刻を指定し、frameTimestampとdocの関連するグローバルオブジェクトをタイムスタンプとして渡します。
unsafeStyleAndLayoutStartTime を 安全でない共有現在時刻に設定します。
各docについて:
resizeObserverDepthを0に設定します。
無限ループの間:
docのスタイルを再計算し、レイアウトを更新します。
hadInitialVisibleContentVisibilityDeterminationをfalseに設定します。
'auto'を使用した 'content-visibility'の値を持つ各要素elementについて:
もしelementのビューポートとの近接性がまだ決定されておらず、それがユーザーに関連しているものでない場合は、checkForInitialDeterminationをtrueに設定します。そうでない場合は、checkForInitialDeterminationをfalseに設定します。
elementのビューポートとの近接性を決定します。
もしcheckForInitialDeterminationがtrueであり、elementが現在ユーザーに関連しているものである場合、hadInitialVisibleContentVisibilityDeterminationをtrueに設定します。
もしhadInitialVisibleContentVisibilityDeterminationがtrueであれば、続行します。
このステップの目的は、すぐに反映される初期のビューポート近接性の決定が、このループの前のステップで行われたスタイルおよびレイアウトの計算に反映されることです。初期以外の近接性の決定は、次のレンダリングの機会で効果を発揮します。[CSSCONTAIN]
深度でアクティブなリサイズ観測を集める resizeObserverDepthをdocに設定します。
もしdocがアクティブなリサイズ観測を持っている場合:
アクティブなリサイズ観測を通知した結果をdocに基づいてresizeObserverDepthに設定します。
もしdocがスキップされたリサイズ観測を持っている場合、リサイズループエラーを送信します。
各docについて、もしdocのフォーカスされた領域がフォーカス可能な領域でない場合、docのビューポートに対してフォーカス修正手順を実行し、docの関連するグローバルオブジェクトのナビゲーションAPIの進行中のナビゲーション中にフォーカスが変更されたをfalseに設定します。
例えば、要素に属性が追加され、レンダリングされなくなることが原因でこれが発生することがあります。また、要素が無効化されたときに、input要素に対しても発生することがあります。
これは通常、blurイベント、そして場合によってはchangeイベントを発生させます。
この非同期修正に加えて、もしドキュメントのフォーカスされた領域が削除された場合、同期修正が行われます。この修正では、blurまたはchangeイベントは発生しません。
各docについて、保留中の遷移操作を実行します。[CSSVIEWTRANSITIONS]
各docについて、交差観測の更新手順を実行し、相対的な高解像度時刻をnowおよびdocの関連するグローバルオブジェクトに渡してタイムスタンプとして設定します。[INTERSECTIONOBSERVER]
各docについて、レンダリング時間を記録します。docにunsafeStyleAndLayoutStartTimeを指定して。
各docについて、ペイントタイミングをマークします。docに対して。
各docについて、docおよびそのナビゲーブルノードのレンダリングまたはユーザーインターフェースを現在の状態を反映するように更新します。
各docについて、トップレイヤーの削除を処理します。docに対して。
ナビゲーブルは、ユーザーエージェントが現在、ナビゲーブルの内容をユーザーに提示できる場合、ハードウェアのリフレッシュレート制約やパフォーマンスのためのユーザーエージェントのスロットリングを考慮して、レンダリング機会を持ちます。ただし、ビューポート外のコンテンツも提示可能であると見なします。
ナビゲーブルのレンダリング機会は、ディスプレイのリフレッシュレートなどのハードウェアの制約や、ページのパフォーマンス、あるいはアクティブなドキュメントの可視状態が"visible"であるかどうかなどの他の要因に基づいて決定されます。レンダリング機会は通常、定期的な間隔で発生します。
この仕様は、レンダリング機会を選択するための特定のモデルを要求していません。ただし、例えばブラウザが60Hzのリフレッシュレートを達成しようとしている場合、レンダリング機会は最大で1秒の60分の1(約16.7ms)ごとに発生します。ブラウザがナビゲーブルがこのレートを維持できないと判断した場合、時折フレームを落とすのではなく、そのナビゲーブルに対してより持続可能な1秒間に30回のレンダリング機会に切り替えることがあります。同様に、ナビゲーブルが可視状態でない場合、ユーザーエージェントはそのページのレンダリング機会を1秒間に4回、またはそれ以下に減らすことを決定するかもしれません。
ユーザーエージェントがマイクロタスクチェックポイントを実行する場合:
もしイベントループのマイクロタスクチェックポイントを実行中がtrueである場合、リターンします。
イベントループのマイクロタスクチェックポイントを実行中をtrueに設定します。
キューから取り出す結果をoldestMicrotaskに設定します。
oldestMicrotaskを実行します。
これはスクリプトされたコールバックを呼び出すことを含むかもしれません。これが最終的にスクリプトの実行後のクリーンアップ手順を呼び出し、このマイクロタスクチェックポイントを実行するアルゴリズムを再度呼び出すことになります。これが再入を避けるためにマイクロタスクチェックポイントを実行中フラグを使用する理由です。
この環境設定オブジェクトで、責任を持つイベントループがこのイベントループであるsettingsObjectのグローバルオブジェクトに基づいて拒否されたプロミスについて通知を行います。
インデックスデータベーストランザクションのクリーンアップを実行します。
ClearKeptObjects()を実行します。
当WeakRef.prototype.deref()がオブジェクトを返す場合、そのオブジェクトは次のClearKeptObjects()の呼び出しまで生存し、その後再びガベージコレクションの対象となります。
イベントループのマイクロタスクチェックポイントを実行中をfalseに設定します。
アルゴリズムが並行して実行されるときに安定状態を待機するとき、ユーザーエージェントは次のステップを実行するマイクロタスクをキューに入れ、その後の実行を停止します(アルゴリズムの実行は、マイクロタスクが実行されると再開されます)。
アルゴリズムの同期セクションを実行します。
適切な場合は、アルゴリズムのステップに従って並行してアルゴリズムの実行を再開します。
同期セクションのステップには⌛が付いています。
イベントループをスピンすると言うアルゴリズムステップは、goalが満たされるまで、次のアルゴリズムステップに置き換えることと同等です。
taskはマイクロタスクである可能性があります。
taskのタスクソースをtask sourceに設定します。
JavaScript実行コンテキストスタックのコピーをold stackに設定します。
JavaScript実行コンテキストスタックを空にします。
もしtaskがマイクロタスクである場合、このステップは、マイクロタスクチェックポイントを実行中がtrueであるため、何も行わないでしょう。
並行して:
goalが満たされるまで待ちます。
タスクをキューに入れるして、task sourceに:
JavaScript実行コンテキストスタックをold stackに置き換えます。
元のアルゴリズムでこのイベントループをスピンするインスタンスの後に現れるすべてのステップを実行します。
これによりtaskが再開されます。
taskを停止し、それを呼び出したアルゴリズムが再開できるようにします。
これによりイベントループのメインステップセットまたはマイクロタスクチェックポイントを実行するアルゴリズムが続行されます。
このおよび他の仕様内の他のアルゴリズムとは異なり、プログラミング言語の関数呼び出しに類似した動作をするものとは異なり、イベントループをスピンするは、マクロに似ています。これにより、使用場所でのタイピングやインデントを省き、一連のステップと操作に展開されます。
ステップが次のようなアルゴリズム:
何かを行う。
イベントループをスピンするまで待ちます。
次のことを行う。
は、"マクロ展開"された後に次のようになります
何かを行う。
JavaScript実行コンテキストスタックのコピーをold stackに設定します。
JavaScript実行コンテキストスタックを空にします。
並行して:
驚異が起こるまで待ちます。
タスクをキューに入れるして、"何かを行う"を行ったタスクソースに:
JavaScript実行コンテキストスタックをold stackに置き換えます。
次のことを行う。
以下は、並行して作業を行うタスク内でイベントループがスピンされる、置換のより完全な例です。イベントループをスピンするを使用したバージョン:
並行して:
並行して行う作業1を実行します。
タスクをキューに入れるして、DOM操作タスクソースで以下を実行します:
タスクの作業1を実行します。
イベントループをスピンするまで待ちます。
タスクの作業2を実行します。
並行して行う作業2を実行します。
完全に展開されたバージョン:
並行して:
並行して行う作業1を実行します。
old stackをnullに設定します。
タスクをキューに入れるして、DOM操作タスクソースで以下を実行します:
タスクの作業1を実行します。
JavaScript実行コンテキストスタックのコピーをold stackに設定します。
JavaScript実行コンテキストスタックを空にします。
驚異が起こるまで待ちます。
タスクをキューに入れるして、DOM操作タスクソースで以下を実行します:
JavaScript実行コンテキストスタックをold stackに置き換えます。
タスクの作業2を実行します。
並行して行う作業2を実行します。
この仕様の一部のアルゴリズムでは、歴史的な理由により、ユーザーエージェントがgoalという条件が満たされるまで、タスクを実行している間に一時停止することが求められます。これは、次の手順を実行することを意味します:
globalを現在のグローバルオブジェクトに設定します。
timeBeforePauseを現在の高解像度時間に設定します。globalを指定します。
必要に応じて、Documentまたはナビゲーブルのレンダリングまたはユーザーインターフェースを更新して、現在の状態を反映させます。
goalという条件が満たされるまで待ちます。ユーザーエージェントが一時停止されたタスクを持っている間、対応するイベントループはそれ以上タスクを実行せず、現在実行中のタスク内のスクリプトはブロックされます。ただし、一時停止中でもユーザー入力には応答する必要がありますが、イベントループは何もしていないため、応答性は低下します。
一時停止の期間を記録します。timeBeforePauseからglobalを指定して時間の長さを記録します。
一時停止は、特に複数のドキュメントが1つのイベントループを共有するシナリオでは、ユーザーエクスペリエンスに非常に悪影響を与えます。ユーザーエージェントは、一時停止に代わる方法を模索することが推奨されます。例えば、イベントループをスピンする、あるいは単に一時停止なしで処理を続行するなど、既存のコンテンツとの互換性を維持できる範囲で模索します。この仕様は、Web互換性が確認されるより穏やかな代替案が発見された場合、喜んで変更されます。
その間、実装者は、ユーザーエージェントが模索する可能性のあるさまざまな代替案が、イベントループの動作、タスクおよびマイクロタスクのタイミングなどの微妙な側面を変える可能性があることに注意する必要があります。一時停止操作によって暗示される正確な意味を違反することになっても、実装は引き続き実験を続けるべきです。
以下のタスクソースは、この仕様および他の仕様で主に無関係な複数の機能によって使用されます。
このタスクソースは、要素がドキュメントに挿入されたときに非ブロッキングの方式で発生する事象のように、DOM操作に反応する機能に使用されます。
このタスクソースは、キーボードやマウス入力など、ユーザーの操作に反応する機能に使用されます。
ユーザー入力に応じて送信されるイベント(例: clickイベント)は、ユーザーインタラクションタスクソースでキューに入れられたタスクを使用して発火されなければなりません。[UIEVENTS]
このタスクソースは、ネットワーク活動に応じてトリガーされる機能に使用されます。
イベントループと正しく相互作用する仕様を書くことは難しい場合があります。この仕様では並行性モデルに依存しない用語を使用しているため、「イベントループ」や「並行して」といった表現を使い、より馴染みのある「メインスレッド」や「バックグラウンドスレッド上で」といったモデル固有の用語は使用していません。
通常、仕様のテキストはイベントループ上で実行されます。これは、正式なイベントループ処理モデルに基づき、ほとんどのアルゴリズムが最終的にはタスクにキューに入れられるところにまで遡ることができるためです。
JavaScriptメソッドのアルゴリズムステップは、著者コードによってそのメソッドが呼び出されることで実行されます。そして、著者コードは通常、script処理モデルのどこかで発生したキューに入れられたタスクを介してのみ実行されます。
この出発点から、主要なガイドラインは、イベントループをブロックする可能性がある仕様が行う必要のある作業は、並行して実行されなければならないということです。これには以下を含みますが、これらに限定されません:
重い計算の実行;
ユーザー向けのプロンプトの表示;
外部システムを関与させる必要がある操作の実行(例:「プロセス外の」操作)。
次に考慮すべき点は、並行して実行されるアルゴリズムセクションでは、特定のRealm、グローバル、または環境設定オブジェクトに関連付けられたオブジェクトを作成したり操作したりしてはならないということです。これは、バックグラウンドスレッドからメインスレッドのアーティファクトに直接アクセスしてはならないという、より馴染みのある用語で述べられます。これを行うと、アルゴリズムのステップがJavaScriptコードと並行して実行されるため、JavaScriptコードから観察可能なデータ競合が発生する可能性があります。
しかし、Infraのような仕様レベルのデータ構造や値を操作することは可能です。これらはRealmに依存しません。特定の変換が行われない限り(しばしばWeb IDLを介して)、JavaScriptには直接公開されません。[INFRA] [WEBIDL]
そのため、観察可能なJavaScriptオブジェクトの世界に影響を与えるには、そのような操作を実行するためにグローバルタスクをキューに入れる必要があります。これにより、イベントループ上で発生している他の事象と適切にステップがインターリーブされます。さらに、タスクソースを選択してグローバルタスクをキューに入れる必要があります。これにより、他のステップに対する相対的な順序が決定されます。どのタスクソースを使用するか不明な場合は、最も適用可能と思われる汎用タスクソースの1つを選択します。最後に、キューに入れたタスクが関連付けられるグローバルオブジェクトを指定する必要があります。これにより、そのグローバルオブジェクトが非アクティブである場合、タスクが実行されないようにします。
グローバルタスクをキューに入れる基盤となる基本的なプリミティブは、タスクをキューに入れるアルゴリズムです。一般的に、グローバルタスクをキューに入れるの方が優れています。なぜなら、これは自動的に適切なイベントループや、適切な場合にはドキュメントを選択するからです。古い仕様では、暗黙のイベントループや暗黙のドキュメントの概念と組み合わせてタスクをキューに入れるが使用されることがありますが、これは推奨されません。
これらをまとめると、非同期で作業を行う必要がある典型的なアルゴリズムのテンプレートを提供できます:
イベントループ上で、すべての同期セットアップ作業を行います。これには、Realm固有のJavaScript値をRealmに依存しない仕様レベルの値に変換することが含まれる場合があります。
Realmに依存しない値のみを操作し、Realmに依存しない結果を生成するために、並行して一連の潜在的に高コストなステップを実行します。
指定されたタスクソースと適切なグローバルオブジェクトを指定して、グローバルタスクをキューに入れることで、Realmに依存しない結果をイベントループ上のJavaScriptオブジェクトの観察可能な世界への観察可能な影響に変換します。
以下は、リストとして渡されたスカラー値文字列のinputをURLとして解析し、それらを「暗号化」するアルゴリズムです:
urlsを空のリストに設定します。
各stringをinputで繰り返します:
parsedをURLをエンコード解析するの結果に設定し、stringと現在の設定オブジェクトを相対的にします。
parsedが失敗した場合、a promise rejected withを"SyntaxError" DOMExceptionで返します。
serializedをURLシリアライザーをparsedに適用した結果に設定します。
追加して、serializedをurlsに設定します。
realmを現在のRealmに設定します。
pを新しいプロミスに設定します。
次のステップを並行して実行します:
encryptedURLsを空のリストに設定します。
各urlをurlsで繰り返します:
グローバルタスクをキューに入れるをネットワーキングタスクソースで実行し、realmのグローバルオブジェクトを指定して、次のステップを実行します:
arrayを、encryptedURLsをJavaScript配列に変換した結果に設定します。realmで実行します。
pをarrayで解決します。
pを返します。
このアルゴリズムに関するいくつかの注意点を以下に示します:
URLの解析をイベントループ上で、並行してステップに進む前に行います。これは、解析が現在の設定オブジェクトに依存しており、並行して進んだ後はもはや現在の状態でなくなるためです。
または、現在の設定オブジェクトのAPIベースURLへの参照を保存し、並行してステップで使用することもできます。それでも同等です。しかし、この例のように、できる限り多くの作業を前もって行うことをお勧めします。正しい値を保存しようとすることはエラーを招きやすく、例えば、現在の設定オブジェクトだけを保存し、APIベースURLを保存しなかった場合、レースコンディションが発生する可能性があります。
アルゴリズムの最初のステップから並行してステップにリストとして文字列を渡します。これは問題ありません。Realmに依存しないためです。
「高コストな計算」(各入力URLに対して100ミリ秒待機)を並行してステップで実行し、メインイベントループをブロックしません。
プロミスは観察可能なJavaScriptオブジェクトであるため、並行してステップで作成や操作が行われることはありません。pはこれらのステップに入る前に作成され、その後、特にその目的のためにキューに入れられたタスクで操作されます。
JavaScript配列オブジェクトの作成も、キューに入れられたタスクの中で行われ、その配列が作成されるRealmを指定します。これは文脈からは明らかでなくなっているため、注意が必要です。
(これら最後の2つの点については、whatwg/webidl issue #135およびwhatwg/webidl issue #371も参照してください。上記のプロミス解決パターンの微妙な点についてまだ検討中です。)
もう一つ注目すべき点は、このアルゴリズムがWeb IDLで指定された操作から呼び出された場合に、sequence<USVString>を取ると、著者が入力として提供したRealm固有のJavaScriptオブジェクトから、Realmに依存しないsequence<USVString>
Web IDL型に自動変換され、それをリストとして扱い、スカラー値文字列を処理することです。したがって、仕様がどのように構成されているかに応じて、メインイベントループ上で発生する他の暗黙的なステップが、この一連のプロセスの一部を担う場合があります。
多くのオブジェクトには、イベントハンドラーを指定できます。これらは、指定されたオブジェクトの非キャプチャイベントリスナーとして機能します。[DOM]
イベントハンドラーは、2つの構造体を持つ項目で構成されています。
値は、null、コールバックオブジェクト、または内部の未コンパイルハンドラーのいずれかです。EventHandlerコールバック関数のタイプは、これがスクリプトにどのように公開されるかを説明します。初期状態では、イベントハンドラーの値はnullに設定されている必要があります。
リスナーは、nullまたはイベントリスナーであり、イベントハンドラープロセスアルゴリズムを実行する責任があります。初期状態では、イベントハンドラーのリスナーはnullに設定されている必要があります。
イベントハンドラーは2つの方法で公開されます。
最初の方法は、すべてのイベントハンドラーに共通する、イベントハンドラーIDL属性としてです。
2つ目の方法は、イベントハンドラーコンテンツ属性としてです。HTML要素上のイベントハンドラーや、Windowオブジェクト上の一部のイベントハンドラーが、この方法で公開されます。
これら2つの方法のどちらにおいても、イベントハンドラーは、必ず「on」で始まり、そのハンドラーが意図するイベントの名前が続く名前として公開されます。
ほとんどの場合、イベントハンドラーを公開するオブジェクトは、対応するイベントリスナーが追加されたオブジェクトと同じです。しかし、bodyおよびframeset要素はいくつかのイベントハンドラーを公開し、それらは要素のWindowオブジェクトに対して作用します(存在する場合)。いずれの場合でも、このオブジェクトは、イベントハンドラーが作用するターゲットと呼ばれます。
イベントハンドラーのターゲットを決定するために、指定されたEventTargetオブジェクトeventTargetと、イベントハンドラーが公開されているnameを用いて、次の手順が行われます。
nameがWindowEventHandlersインターフェイスミックスインの属性メンバーの名前でない場合、およびWindowに反映されるbody要素のイベントハンドラーセットがnameを含んでいない場合、eventTargetを返します。
eventTargetのノードドキュメントがアクティブドキュメントでない場合、nullを返します。
これは、たとえば対応するbody要素が存在しない場合に発生する可能性があります。
このチェックは、bodyおよびframeset要素が、ドキュメントのノードドキュメントに接続されていなくても、次のステップに進むことを妨げるわけではありません。特に、アクティブドキュメント内で作成されたが接続されていないbody要素も、対応するWindowオブジェクトが、いくつかのイベントハンドラーのターゲットとして機能する可能性があります。
eventTargetのノードドキュメントの関連するグローバルオブジェクトを返します。
1つ以上のイベントハンドラーが指定されたEventTargetオブジェクトには、関連するイベントハンドラーマップがあります。これは、マップで、名前と、それに対応するイベントハンドラーが含まれています。
1つ以上のイベントハンドラーが指定されたEventTargetオブジェクトが作成されると、そのイベントハンドラーマップが初期化され、そのオブジェクトがターゲットとなる各イベントハンドラーのエントリを含むように設定されます。
エントリの順序は任意です。これは、マップ上で動作するアルゴリズムによって観測可能ではありません。
エントリは、単にそのオブジェクト上に公開されているが、他のオブジェクトをターゲットとしているイベントハンドラーの場合、オブジェクトのイベントハンドラーマップには作成されません。
イベントハンドラーIDL属性は、特定のイベントハンドラーのためのIDL属性です。このIDL属性の名前は、名前と同じです。
イベントハンドラーIDL属性のゲッターは、次の手順を実行します。
このオブジェクトとnameを指定して、イベントハンドラーのターゲットを決定する結果として、eventTargetを取得します。
もしeventTargetがnullである場合、nullを返します。
eventTargetとnameを指定して、イベントハンドラーの現在の値を取得する結果を返します。
イベントハンドラーIDL属性のセッターは、次の手順を実行します。
このオブジェクトとnameを指定して、イベントハンドラーのターゲットを決定する結果として、eventTargetを取得します。
もしeventTargetがnullである場合、処理を終了します。
指定された値がnullである場合、eventTargetとnameを指定して、イベントハンドラーを無効化します。
それ以外の場合は次の手順を実行します。
eventTargetのイベントハンドラーマップをhandlerMapに設定します。
handlerMap[name]をeventHandlerに設定します。
eventHandlerの値を指定された値に設定します。
eventTargetとnameを指定して、イベントハンドラーを有効化します。
特定のイベントハンドラーIDL属性には追加の要件があります。特に、onmessage属性や、MessagePortオブジェクトの属性です。
イベントハンドラーコンテンツ属性は、特定のイベントハンドラーのためのコンテンツ属性です。このコンテンツ属性の名前は、イベントハンドラーの名前と同じです。
イベントハンドラーコンテンツ属性は、有効なJavaScriptコードを含んでいる必要があり、パース時にFunctionBodyプロダクションに一致しなければなりません。自動セミコロン挿入後に一致する必要があります。
次の属性変更手順は、イベントハンドラーコンテンツ属性とイベントハンドラーを同期させるために使用されます。[DOM]
namespaceがnullでない場合、またはlocalNameがelementのイベントハンドラーコンテンツ属性の名前でない場合は、処理を終了します。
eventTargetを、elementとlocalNameを指定してイベントハンドラーのターゲットを決定する結果として取得します。
もしeventTargetがnullである場合、処理を終了します。
もしvalueがnullである場合、eventTargetとlocalNameを指定してイベントハンドラーを無効化します。
それ以外の場合は次の手順を実行します。
もしコンテンツセキュリティポリシーによって要素のインライン動作がブロックされるかどうかのアルゴリズムが、element、"script attribute"、およびvalueに対して実行されたときに"Blocked"を返す場合、処理を終了します。[CSP]
handlerMapをeventTargetのイベントハンドラーマップに設定します。
eventHandlerをhandlerMap[localName]に設定します。
これらの手順を引き起こしたスクリプトの位置をlocationに設定します。
eventHandlerの値を、value/locationの内部の未コンパイルハンドラーに設定します。
eventTargetとlocalNameを指定してイベントハンドラーを有効化します。
DOM標準に従って、これらの手順はoldValueとvalueが同一の場合でも実行されますが、oldValueとvalueが両方ともnullである場合(現在存在しない属性を削除する場合)は実行されません。[DOM]
イベントハンドラーを無効化するために、eventTargetオブジェクトEventTargetと文字列name(イベントハンドラーの名前)を指定して、次の手順を実行します。
handlerMapをeventTargetのイベントハンドラーマップに設定します。
eventHandlerをhandlerMap[name]に設定します。
eventHandlerの値をnullに設定します。
listenerをeventHandlerのリスナーに設定します。
もしlistenerがnullでない場合、eventTargetとlistenerを指定してイベントリスナーを削除します。
eventHandlerのリスナーをnullに設定します。
すべてのイベントリスナーとハンドラーを消去するために、eventTargetオブジェクトEventTargetを指定して、次の手順を実行します。
もしeventTargetに関連するイベントハンドラーマップが存在する場合、eventTargetの関連するイベントハンドラーマップ内の各name → eventHandlerについて、eventTargetとnameを指定してイベントハンドラーを無効化します。
eventTargetを指定してすべてのイベントリスナーを削除します。
このアルゴリズムは、document.open()を定義するために使用されます。
イベントハンドラーを有効化するために、eventTargetオブジェクトEventTargetと文字列name(イベントハンドラーの名前)を指定して、次の手順を実行します。
handlerMapをeventTargetのイベントハンドラーマップに設定します。
eventHandlerをhandlerMap[name]に設定します。
もしeventHandlerのリスナーがnullでない場合、処理を終了します。
1つの引数を持つ関数への参照を表すWeb IDL EventListenerインスタンスを作成し、callbackに設定します。この関数はeventTarget、name、およびその引数を指定して、イベントハンドラープロセスアルゴリズムの手順を実行します。
EventListenerのコールバックコンテキストは任意であり、イベントハンドラープロセスアルゴリズムの手順には影響しません。[DOM]
このコールバックは、イベントハンドラー自体ではありません。すべてのイベントハンドラーは、以下に定義されている同じアルゴリズムを登録し、正しいコードの呼び出しとその戻り値の処理を行います。
listenerを新しいイベントリスナーに設定します。listenerのタイプはeventHandlerに対応するイベントハンドラーイベントタイプであり、callbackはコールバックです。
イベントリスナーはEventListenerとは異なるものであることに注意してください。
eventTargetとlistenerを指定してイベントリスナーを追加します。
eventHandlerのリスナーをlistenerに設定します。
イベントリスナーの登録は、イベントハンドラーの値がnull以外に設定されており、無効化されていない場合にのみ行われます。特定のイベントタイプのイベントリスナーの順序は、常に次のようになります。
最初にaddEventListener()を使用して登録されたイベントリスナー
次に、現在設定されているコールバック(存在する場合)
そして、最初にイベントハンドラーの値がnull以外に設定された後にaddEventListener()を使用して登録されたイベントリスナー
この例は、イベントリスナーが呼び出される順序を示しています。この例でボタンがユーザーによってクリックされると、ページには"ONE"、"TWO"、"THREE"、"FOUR"という4つのアラートが順に表示されます。
< button id = "test" > Start Demo</ button >
< script >
var button = document. getElementById( 'test' );
button. addEventListener( 'click' , function () { alert( 'ONE' ) }, false );
button. setAttribute( 'onclick' , "alert('NOT CALLED')" ); // event handler listener is registered here
button. addEventListener( 'click' , function () { alert( 'THREE' ) }, false );
button. onclick = function () { alert( 'TWO' ); };
button. addEventListener( 'click' , function () { alert( 'FOUR' ) }, false );
</ script >
しかし、次の例では、イベントハンドラーが初期の有効化後に無効化され(およびそのイベントリスナーが削除され)、後で再度有効化されます。ページには"ONE"、"TWO"、"THREE"、"FOUR"、"FIVE"という5つのアラートが順に表示されます。
< button id = "test" > Start Demo</ button >
< script >
var button = document. getElementById( 'test' );
button. addEventListener( 'click' , function () { alert( 'ONE' ) }, false );
button. setAttribute( 'onclick' , "alert('NOT CALLED')" ); // event handler is activated here
button. addEventListener( 'click' , function () { alert( 'TWO' ) }, false );
button. onclick = null ; // but deactivated here
button. addEventListener( 'click' , function () { alert( 'THREE' ) }, false );
button. onclick = function () { alert( 'FOUR' ); }; // and re-activated here
button. addEventListener( 'click' , function () { alert( 'FIVE' ) }, false );
</ script >
イベントオブジェクトによって実装されているインターフェイスは、イベントハンドラーがトリガーされるかどうかには影響しません。
イベントハンドラープロセスアルゴリズムは、eventTargetオブジェクトEventTarget、名前を表す文字列name、およびeventオブジェクトEventに対して次の手順を実行します。
callbackを、eventTargetとnameを指定してイベントハンドラーの現在の値を取得する結果として取得します。
もしcallbackがnullである場合、処理を終了します。
もしeventがErrorEventオブジェクトであり、eventのtypeが"error"であり、eventのcurrentTargetがWindowOrWorkerGlobalScopeミックスインを実装している場合、special
error event handlingをtrueに設定します。それ以外の場合は、special error event handlingをfalseに設定します。
eventオブジェクトを次のように処理します。
return value を、コールバックを次のように呼び出した結果とします:event
の message、event
の filename、event
の lineno、event
の colno、および
event の error
の値と、"rethrow"、そして callback this value
を event の currentTarget
に設定します。
return value を、コールバックを次のように呼び出した結果とします:event、"rethrow"、および
callback this value
を event の currentTarget
に設定します。
コールバックによって例外がスローされた場合、その例外は再スローされ、これらの手順は終了します。例外はDOMイベントディスパッチロジックに伝播し、報告されます。
return valueを次のように処理します。
BeforeUnloadEventオブジェクトであり、eventのtypeが"beforeunload"である場合
この場合、イベントハンドラーIDL属性のタイプはOnBeforeUnloadEventHandlerであり、return
valueはnullまたはDOMStringに強制されます。
もしreturn valueがnullでない場合、次の手順を実行します。
eventのキャンセルフラグを設定します。
もしeventのreturnValue属性の値が空文字列である場合、eventのreturnValue属性の値をreturn
valueに設定します。
もしreturn valueがtrueである場合、eventのキャンセルフラグを設定します。
もしreturn valueがfalseである場合、eventのキャンセルフラグを設定します。
もしeventのtypeが"beforeunload"であるためにこの"それ以外の場合"の節に到達した場合、しかしeventがBeforeUnloadEventオブジェクトでない場合、return
valueがfalseになることはありません。この場合、return valueはnullまたはDOMStringに強制されます。
イベントハンドラー
コールバック
関数タイプは、イベントハンドラーに使用されるコールバックを表します。これは、次のようにWeb IDLで表されます:
[LegacyTreatNonObjectAsNull ]
callback EventHandlerNonNull = any (Event event );
typedef EventHandlerNonNull ? EventHandler ;
JavaScriptでは、任意の Function
オブジェクトがこのインターフェースを実装します。
例えば、次のドキュメントフラグメントは:
< body onload = "alert(this)" onclick = "alert(this)" >
...ドキュメントが読み込まれると「[object Window]」というアラートが表示され、ページ内の何かをクリックすると「[object HTMLBodyElement]」というアラートが表示されます。
関数の戻り値は、イベントがキャンセルされるかどうかに影響を与えます: 上記のように、戻り値が false である場合、イベントはキャンセルされます。
歴史的な理由から、プラットフォームには2つの例外があります:
グローバルオブジェクト上の onerror
ハンドラーでは、true を返すとイベントがキャンセルされます。
onbeforeunload
ハンドラーでは、null でも undefined でもない値を返すとイベントがキャンセルされます。
歴史的な理由から、onerror
ハンドラーには異なる引数があります:
[LegacyTreatNonObjectAsNull ]
callback OnErrorEventHandlerNonNull = any ((Event or DOMString ) event , optional DOMString source , optional unsigned long lineno , optional unsigned long colno , optional any error );
typedef OnErrorEventHandlerNonNull ? OnErrorEventHandler ;
window. onerror = ( message, source, lineno, colno, error) => { … };
同様に、onbeforeunload
ハンドラーには異なる戻り値があります:
[LegacyTreatNonObjectAsNull ]
callback OnBeforeUnloadEventHandlerNonNull = DOMString ? (Event event );
typedef OnBeforeUnloadEventHandlerNonNull ? OnBeforeUnloadEventHandler ;
内部の未コンパイルハンドラーは、以下の情報を含むタプルです:
未コンパイルのスクリプトボディ
エラーが報告される必要がある場合に備えて、スクリプトボディが発生した場所
ユーザーエージェントが、EventTarget
オブジェクトeventTargetとイベントハンドラーの名前である文字列nameが与えられた場合に、イベントハンドラーの現在の値を取得するためには、次の手順を実行する必要があります:
handlerMapをeventTargetのイベントハンドラーマップに設定します。
eventHandlerをhandlerMap[name]に設定します。
もしeventHandlerの値が内部の未コンパイルハンドラーである場合、次のステップを実行します:
もしeventTargetが要素であれば、elementをeventTargetに設定し、documentをelementのノードドキュメントに設定します。そうでなければ、eventTargetはWindowオブジェクトであり、elementをnullに設定し、documentをeventTargetの関連付けられたDocumentに設定します。
もしスクリプトが無効である場合、documentに対して、nullを返します。
bodyをeventHandlerの値内の未コンパイルスクリプトボディに設定します。
locationをeventHandlerの値によって与えられる、スクリプトボディの発生元の場所に設定します。
もしelementがnullでなく、elementがフォームオーナーを持っている場合、そのフォームオーナーをform ownerに設定します。そうでなければ、form ownerをnullに設定します。
設定オブジェクトをdocumentの関連設定オブジェクトに設定します。
もしbodyがFunctionBodyとしてパース可能でない場合、またはパース中に初期エラーを検出した場合、次のサブステップに従います:
eventHandlerの値をnullに設定します。
これによって、イベントハンドラーが非アクティブ化されるわけではなく、追加でイベントハンドラーのリスナーの削除(存在する場合)が行われます。
syntaxErrorを、設定オブジェクトのレルムに関連付けられた新しいSyntaxError例外に設定します。この例外は、パース中に発生したエラーを記述します。これは、スクリプトボディが発生したlocationに基づくべきです。
例外を報告し、設定オブジェクトのグローバルオブジェクトに対してsyntaxErrorを報告します。
nullを返します。
設定オブジェクトのレルム実行コンテキストをJavaScript実行コンテキストスタックにプッシュします。これにより、実行中のJavaScript実行コンテキストとなります。
これが必要なのは、後続のOrdinaryFunctionCreateの呼び出しが正しいレルムで行われるようにするためです。
functionを、以下の引数を使用してOrdinaryFunctionCreateを呼び出した結果に設定します:
realmを設定オブジェクトのレルムに設定します。
scopeをrealmの[[GlobalEnv]]に設定します。
もしeventHandlerが要素のイベントハンドラーである場合、scopeをNewObjectEnvironment(document, true, scope)に設定します。
もしform ownerがnullでなければ、scopeをNewObjectEnvironment(form owner, true, scope)に設定します。
もしelementがnullでなければ、scopeをNewObjectEnvironment(element, true, scope)に設定します。
scopeを返します。
設定オブジェクトのレルム実行コンテキストをJavaScript実行コンテキストスタックから削除します。
functionの[[ScriptOrModule]]をnullに設定します。
これは、スタック上で作成された関数を最も近いスクリプトに関連付けるというデフォルトの動作が、パス依存の結果につながる可能性があるためです。例えば、最初にユーザーの操作で呼び出されたイベントハンドラーは、[[ScriptOrModule]]がnullに設定されます(このアルゴリズムが最初に実行されたとき、アクティブスクリプトがnullである場合)、一方でスクリプトからイベントをディスパッチすることで最初に呼び出されたものは、そのスクリプトに[[ScriptOrModule]]が設定されます。
代わりに、常に[[ScriptOrModule]]をnullに設定します。これはより直感的です。イベントハンドラーコードに対して最初にイベントをディスパッチするスクリプトが何らかの形で責任を負うという考えは疑わしいです。
実際には、これはスクリプトのベースURLを参照するHostLoadImportedModuleを介して相対URLの解決にのみ影響します。[[ScriptOrModule]]をnullに設定することで、HostLoadImportedModuleが現在の設定オブジェクトのAPIベースURLにフォールバックすることになります。
eventHandlerの値を、オブジェクト参照がfunctionであり、コールバックコンテキストが設定オブジェクトであるWeb IDLのEventHandlerコールバック関数オブジェクトを作成する結果に設定します。
eventHandlerの値を返します。
Document
オブジェクト、およびWindow
オブジェクトのイベントハンドラー
以下は、すべてのHTML要素
がサポートしなければならないイベントハンドラー(および対応するイベントハンドラーイベントタイプ)です。これらは、イベントハンドラーコンテンツ属性およびイベントハンドラーIDL属性の両方として、またすべてのDocumentおよびWindowオブジェクトがイベントハンドラーIDL属性としてサポートしなければなりません:
| イベントハンドラー | イベントハンドラーイベントタイプ |
|---|---|
onabort
すべての現行エンジンでサポートされています。 Firefox9+Safari3.1+Chrome3+
Opera12.1+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android?Samsung Internet?Opera Android12.1+ | abort
|
onauxclick
Firefox53+SafariNoChrome55+
Opera?Edge79+ Edge (Legacy)?Internet ExplorerNo Firefox Android53+Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android? | auxclick
|
onbeforeinput
| beforeinput
|
onbeforematch
| beforematch
|
onbeforetoggle
| beforetoggle
|
oncancel
HTMLDialogElement/cancel_event すべての現行エンジンでサポートされています。 Firefox98+Safari15.4+Chrome37+
Opera?Edge79+ Edge (Legacy)?Internet ExplorerNo Firefox Android?Safari iOS?Chrome AndroidNoWebView Android?Samsung Internet?Opera Android? | cancel
|
oncanplay
HTMLMediaElement/canplay_event すべての現行エンジンでサポートされています。 Firefox3.5+Safari3.1+Chrome3+
Opera10.5+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android11+ | canplay
|
oncanplaythrough
HTMLMediaElement/canplaythrough_event すべての現行エンジンでサポートされています。 Firefox3.5+Safari3.1+Chrome3+
Opera10.5+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android11+ | canplaythrough
|
onchange
すべての現行エンジンでサポートされています。 Firefox1+Safari3+Chrome1+
Opera9+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android10.1+ | change
|
onclick
すべての現行エンジンでサポートされています。 Firefox6+Safari3+Chrome1+
Opera11.6+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android6+Safari iOS1+Chrome Android?WebView Android?Samsung Internet?Opera Android12.1+ | click
|
onclose
| close
|
oncontextlost
| contextlost
|
oncontextmenu
| contextmenu
|
oncontextrestored
| contextrestored
|
oncopy
すべての現在のエンジンでサポートされています。 Firefox22+Safari3+Chrome1+
Opera12.1+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android?Samsung Internet?Opera Android12.1+ | copy
|
oncuechange
HTMLTrackElement/cuechange_event すべての現在のエンジンでサポートされています。 Firefox68+Safari10+Chrome32+
Opera19+Edge79+ Edge (Legacy)14+Internet Explorerサポートなし Firefox Android?Safari iOS?Chrome Android?WebView Android4.4.3+Samsung Internet?Opera Android19+ | cuechange
|
oncut
すべての現在のエンジンでサポートされています。 Firefox22+Safari3+Chrome1+
Opera12.1+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android?Samsung Internet?Opera Android12.1+ | cut
|
ondblclick
すべての現在のエンジンでサポートされています。 Firefox6+Safari3+Chrome1+
Opera11.6+Edge79+ Edge (Legacy)12+Internet Explorer8+ Firefox Android6+Safari iOS1+Chrome AndroidサポートなしWebView Android?Samsung Internet?Opera Android12.1+ | dblclick
|
ondrag
| drag
|
ondragend
| dragend
|
ondragenter
| dragenter
|
ondragleave
| dragleave
|
ondragover
| dragover
|
ondragstart
| dragstart
|
ondrop
| drop
|
ondurationchange
HTMLMediaElement/durationchange_event すべての現在のエンジンでサポートされています。 Firefox3.5+Safari3.1+Chrome3+
Opera10.5+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android11+ | durationchange
|
onemptied
HTMLMediaElement/emptied_event すべての現在のエンジンでサポートされています。 Firefox3.5+Safari3.1+Chrome3+
Opera10.5+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android11+ | emptied
|
onended
すべての現在のエンジンでサポートされています。 Firefox3.5+Safari3.1+Chrome3+
Opera10.5+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android11+ | ended
|
onformdata
| formdata
|
oninput
すべての現在のエンジンでサポートされています。 Firefox6+Safari3.1+Chrome1+
Opera11.6+Edge79+ Edge (Legacy)サポートなしInternet Explorer🔰 9+ Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android12+ | input
|
oninvalid
| invalid
|
onkeydown
すべての現在のエンジンでサポートされています。 Firefox6+Safari1.2+Chrome1+
Opera12.1+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android12.1+ | keydown
|
onkeypress
| keypress
|
onkeyup
すべての現在のエンジンでサポートされています。 Firefox6+Safari1.2+Chrome1+
Opera12.1+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android12.1+ | keyup
|
onloadeddata
HTMLMediaElement/loadeddata_event すべての現在のエンジンでサポートされています。 Firefox3.5+Safari3.1+Chrome3+
Opera10.5+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android11+ | loadeddata
|
onloadedmetadata
HTMLMediaElement/loadedmetadata_event すべての現在のエンジンでサポートされています。 Firefox3.5+Safari3.1+Chrome3+
Opera10.5+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android11+ | loadedmetadata
|
onloadstart
HTMLMediaElement/loadstart_event すべての現在のエンジンでサポートされています。 Firefox6+Safari4+Chrome3+
Opera12.1+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android?Samsung Internet?Opera Android12.1+ | loadstart
|
onmousedown
すべての現在のエンジンでサポートされています。 Firefox6+Safari4+Chrome2+
Opera11.6+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS?Chrome Android?WebView Android37+Samsung Internet?Opera Android12.1+ | mousedown
|
onmouseenter
すべての現在のエンジンでサポートされています。 Firefox10+Safari7+Chrome30+
Opera?Edge79+ Edge (Legacy)12+Internet Explorer5.5+ Firefox Android?Safari iOS?Chrome Android?WebView Android37+Samsung Internet?Opera Android? | mouseenter
|
onmouseleave
すべての現在のエンジンでサポートされています。 Firefox10+Safari7+Chrome30+
Opera?Edge79+ Edge (Legacy)12+Internet Explorer5.5+ Firefox Android?Safari iOS?Chrome Android?WebView Android37+Samsung Internet?Opera Android? | mouseleave
|
onmousemove
すべての現在のエンジンでサポートされています。 Firefox6+Safari4+Chrome2+
Opera11.6+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS?Chrome Android?WebView Android37+Samsung Internet?Opera Android12.1+ | mousemove
|
onmouseout
すべての現在のエンジンでサポートされています。 Firefox6+Safari1+Chrome1+
Opera12.1+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS?Chrome Android?WebView Android37+Samsung Internet?Opera Android12.1+ | mouseout
|
onmouseover
すべての現在のエンジンでサポートされています。 Firefox3+Safari1+Chrome1+
Opera9.5+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS?Chrome Android?WebView Android37+Samsung Internet?Opera Android12.1+ | mouseover
|
onmouseup
すべての現在のエンジンでサポートされています。 Firefox6+Safari4+Chrome2+
Opera11.6+Edge79+ Edge (レガシー)12+Internet Explorer9+ Firefox Android?Safari iOS?Chrome Android?WebView Android37+Samsung Internet?Opera Android12.1+ | mouseup
|
onpaste
すべての現在のエンジンでサポートされています。 Firefox22+Safari3+Chrome1+
Opera12.1+Edge79+ Edge (レガシー)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android12.1+ | paste
|
onpause
すべての現在のエンジンでサポートされています。 Firefox3.5+Safari3.1+Chrome3+
Opera10.5+Edge79+ Edge (レガシー)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android11+ | pause
|
onplay
すべての現在のエンジンでサポートされています。 Firefox3.5+Safari3.1+Chrome3+
Opera10.5+Edge79+ Edge (レガシー)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android11+ | play
|
onplaying
HTMLMediaElement/playing_event すべての現在のエンジンでサポートされています。 Firefox3.5+Safari3.1+Chrome3+
Opera10.5+Edge79+ Edge (レガシー)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android11+ | playing
|
onprogress
HTMLMediaElement/progress_event すべての現在のエンジンでサポートされています。 Firefox6+Safari3.1+Chrome3+
Opera12.1+Edge79+ Edge (レガシー)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android?Samsung Internet?Opera Android12.1+ | progress
|
onratechange
HTMLMediaElement/ratechange_event すべての現在のエンジンでサポートされています。 Firefox3.5+Safari3.1+Chrome3+
Opera10.5+Edge79+ Edge (レガシー)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android11+ | ratechange
|
onreset
| reset
|
onscrollend
Firefox109+SafariなしChrome114+
Opera?Edge114+ Edge (Legacy)?Internet Explorerなし Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android? Firefox109+SafariなしChrome114+
Opera?Edge114+ Edge (Legacy)?Internet Explorerなし Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android? | scrollend
|
onsecuritypolicyviolation
Element/securitypolicyviolation_event 全ての現在のエンジンでサポートされています。 Firefox63+Safari10+Chrome41+
Opera?Edge79+ Edge (Legacy)15+Internet Explorerなし Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android? | securitypolicyviolation
|
onseeked
全ての現在のエンジンでサポートされています。 Firefox3.5+Safari3.1+Chrome3+
Opera10.5+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android11+ | seeked
|
onseeking
HTMLMediaElement/seeking_event すべての現在のエンジンでサポートされています。 Firefox3.5+Safari3.1+Chrome3+
Opera10.5+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android11+ | seeking
|
onselect
すべての現在のエンジンでサポートされています。 Firefox6+Safari1+Chrome1+
Opera12.1+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android12.1+ HTMLTextAreaElement/select_event すべての現在のエンジンでサポートされています。 Firefox6+Safari1+Chrome1+
Opera12.1+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android12.1+ | select
|
onslotchange
HTMLSlotElement/slotchange_event すべての現在のエンジンでサポートされています。 Firefox63+Safari10.1+Chrome53+
Opera?Edge79+ Edge (Legacy)?Internet Explorerなし Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android? | slotchange
|
onstalled
HTMLMediaElement/stalled_event すべての現在のエンジンでサポートされています。 Firefox3.5+Safari3.1+Chrome3+
Opera10.5+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android11+ | stalled
|
onsubmit
すべての現在のエンジンでサポートされています。 Firefox1+Safari3+Chrome1+
Opera8+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS1+Chrome Android?WebView Android?Samsung Internet?Opera Android10.1+ | submit
|
onsuspend
HTMLMediaElement/suspend_event すべての現在のエンジンでサポートされています。 Firefox3.5+Safari3.1+Chrome3+
Opera10.5+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android11+ | suspend
|
ontimeupdate
HTMLMediaElement/timeupdate_event すべての現在のエンジンでサポートされています。 Firefox3.5+Safari3.1+Chrome3+
Opera10.5+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android11+ | timeupdate
|
ontoggle
| toggle
|
onvolumechange
HTMLMediaElement/volumechange_event すべての現在のエンジンでサポートされています。 Firefox6+Safari3.1+Chrome3+
Opera12.1+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android12.1+ | volumechange
|
onwaiting
HTMLMediaElement/waiting_event すべての現在のエンジンでサポートされています。 Firefox6+Safari3.1+Chrome3+
Opera12.1+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android12.1+ | waiting
|
onwebkitanimationend
| webkitAnimationEnd
|
onwebkitanimationiteration
| webkitAnimationIteration
|
onwebkitanimationstart
| webkitAnimationStart
|
onwebkittransitionend
| webkitTransitionEnd
|
onwheel
すべての現在のエンジンでサポートされています。 Firefox17+Safari7+Chrome31+
Opera?Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOSサポートなしChrome Android?WebView Android?Samsung Internet?Opera Android? | wheel
|
以下は、すべてのイベント
ハンドラー(およびその対応するイベント
ハンドラーイベントタイプ)で、すべてのHTML
要素がサポートする必要があるものです。ただし、body
およびframeset
要素は除きます。すべてのイベント
ハンドラーコンテンツ属性およびイベント
ハンドラーIDL属性がサポートされる必要があります。すべてのDocument
オブジェクト、およびすべてのイベント
ハンドラーIDL属性がサポートされる必要があります。すべてのWindow
オブジェクト、およびイベント
ハンドラーIDL属性がサポートされる必要があります。Window
オブジェクト自身で、対応するイベント
ハンドラーコンテンツ属性およびイベント
ハンドラーIDL属性が公開される必要があります。すべてのbody
およびframeset
要素は、そのWindow
オブジェクトの関連する
Documentに属します。
| イベントハンドラー | イベントハンドラーイベントタイプ |
|---|---|
onblur
すべての現在のエンジンでサポートされています。 Firefox24+Safari3.1+Chrome1+
Opera11.6+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android12.1+ すべての現在のエンジンでサポートされています。 Firefox6+Safari5.1+Chrome5+
Opera12.1+Edge79+ Edge (Legacy)12+Internet Explorer11 Firefox Android?Safari iOS?Chrome Android?WebView Android37+Samsung Internet?Opera Android12.1+ | blur
|
onerror
すべての現在のエンジンでサポートされています。 Firefox6+Safari5.1+Chrome10+
Opera?Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS?Chrome Android?WebView Android37+Samsung Internet?Opera Android? | error
|
onfocus
すべての現在のエンジンでサポートされています。 Firefox24+Safari3.1+Chrome1+
Opera11.6+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android12.1+ すべての現在のエンジンでサポートされています。 Firefox6+Safari5.1+Chrome5+
Opera12.1+Edge79+ Edge (Legacy)12+Internet Explorer11 Firefox Android?Safari iOS?Chrome Android?WebView Android37+Samsung Internet?Opera Android12.1+ | focus
|
onload
| load
|
onresize
| resize
|
onscroll
すべての現在のエンジンでサポートされています。 Firefox6+Safari2+Chrome1+
Opera11.6+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android12+ すべての現在のエンジンでサポートされています。 Firefox6+Safari1.3+Chrome1+
Opera12.1+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android12.1+ | scroll
|
このテーブルの最初の列にリストされている名前のイベントハンドラーのセットを、Window反映ボディ要素イベントハンドラーセットと呼びます。
以下は、Window
オブジェクトによってサポートされるべき イベントハンドラー(およびそれに対応する
イベントハンドラーイベントタイプ)であり、Window
オブジェクト自体の イベントハンドラー
IDL 属性 およびすべての body
および frameset
要素に公開される対応する イベントハンドラーコンテンツ属性
および イベントハンドラー
IDL 属性 です。
| イベントハンドラー | イベントハンドラーイベントタイプ |
|---|---|
onafterprint
全ての現行エンジンでサポートされています。 Firefox6+Safari13+Chrome63+
Opera?Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android? | afterprint
|
onbeforeprint
全ての現行エンジンでサポートされています。 Firefox6+Safari13+Chrome63+
Opera?Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android? | beforeprint
|
onbeforeunload
全ての現行エンジンでサポートされています。 Firefox1+Safari3+Chrome1+
Opera12+Edge79+ Edge (Legacy)12+Internet Explorer4+ Firefox Android?Safari iOS1+Chrome Android?WebView Android?Samsung Internet?Opera Android12+ | beforeunload
|
onhashchange
全ての現行エンジンでサポートされています。 Firefox3.6+Safari5+Chrome8+
Opera10.6+Edge79+ Edge (Legacy)12+Internet Explorer8+ Firefox Android?Safari iOS5+Chrome Android?WebView Android37+Samsung Internet?Opera Android11+ | hashchange
|
onlanguagechange
全ての現行エンジンでサポートされています。 Firefox32+Safari10.1+Chrome37+
Opera?Edge79+ Edge (Legacy)?Internet Explorer対応していません Firefox Android4+Safari iOS?Chrome Android?WebView Android?Samsung Internet4.0+Opera Android? | languagechange
|
onmessage
全ての現行エンジンでサポートされています。 Firefox9+Safari4+Chrome60+
Opera?Edge79+ Edge (Legacy)12+Internet Explorer8+ Firefox Android?Safari iOS4+Chrome Android?WebView Android?Samsung Internet?Opera Android47+ | message
|
onmessageerror
全ての現行エンジンでサポートされています。 Firefox6+Safari3.1+Chrome3+
Opera11.6+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android?Samsung Internet?Opera Android12+ 全ての現行エンジンでサポートされています。 Firefox57+Safari16.4+Chrome60+
Opera?Edge79+ Edge (Legacy)18Internet Explorer対応していません Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android47+ | messageerror
|
onoffline
全ての現行エンジンでサポートされています。 Firefox9+Safari4+Chrome3+
Opera?Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android? | offline
|
ononline
全ての現行エンジンでサポートされています。 Firefox9+Safari4+Chrome3+
Opera?Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android? | online
|
onpageswap
| pageswap
|
onpagehide
| pagehide
|
onpagereveal
| pagereveal
|
onpageshow
| pageshow
|
onpopstate
全ての現行エンジンでサポートされています。 Firefox4+Safari5+Chrome5+
Opera11.5+Edge79+ Edge (Legacy)12+Internet Explorer10+ Firefox Android?Safari iOS?Chrome Android?WebView Android37+Samsung Internet?Opera Android11.5+ | popstate
|
onrejectionhandled
全ての現行エンジンでサポートされています。 Firefox69+Safari11+Chrome49+
Opera?Edge79+ Edge (Legacy)?Internet Explorer対応していません Firefox Android?Safari iOS11.3+Chrome Android?WebView Android?Samsung Internet?Opera Android? | rejectionhandled
|
onstorage
全ての現行エンジンでサポートされています。 Firefox45+Safari4+Chrome1+
Opera?Edge79+ Edge (Legacy)15+Internet Explorer9+ Firefox Android?Safari iOS4+Chrome Android?WebView Android37+Samsung Internet?Opera Android? | storage
|
onunhandledrejection
Window/unhandledrejection_event 全ての現行エンジンでサポートされています。 Firefox69+Safari11+Chrome49+
Opera?Edge79+ Edge (Legacy)?Internet Explorer対応していません Firefox Android?Safari iOS11.3+Chrome Android?WebView Android?Samsung Internet?Opera Android? | unhandledrejection
|
onunload
全ての現行エンジンでサポートされています。 Firefox1+Safari3+Chrome1+
Opera4+Edge79+ Edge (Legacy)12+Internet Explorer4+ Firefox Android?Safari iOS1+Chrome Android?WebView Android?Samsung Internet?Opera Android10.1+ | unload
|
このイベント
ハンドラーのリストは、イベント
ハンドラー IDL 属性として、WindowEventHandlers
インターフェースミキシンとして具現化されます。
次に示すのは、イベント
ハンドラー(およびその対応するイベント
ハンドラーイベントタイプ)で、Document
オブジェクト上でサポートされる必要があるイベント
ハンドラー IDL 属性です:
| イベント ハンドラー | イベント ハンドラーイベントタイプ |
|---|---|
onreadystatechange
| readystatechange
|
onvisibilitychange
Document/visibilitychange_event 全ての現行エンジンでサポートされています。 Firefox56+Safari14.1+Chrome62+
Opera49+Edge79+ Edge (Legacy)18Internet Explorer🔰 10+ Firefox Android?Safari iOS?Chrome Android?WebView Android62+Samsung Internet?Opera Android46+ | visibilitychange
|
interface mixin GlobalEventHandlers {
attribute EventHandler onabort ;
attribute EventHandler onauxclick ;
attribute EventHandler onbeforeinput ;
attribute EventHandler onbeforematch ;
attribute EventHandler onbeforetoggle ;
attribute EventHandler onblur ;
attribute EventHandler oncancel ;
attribute EventHandler oncanplay ;
attribute EventHandler oncanplaythrough ;
attribute EventHandler onchange ;
attribute EventHandler onclick ;
attribute EventHandler onclose ;
attribute EventHandler oncontextlost ;
attribute EventHandler oncontextmenu ;
attribute EventHandler oncontextrestored ;
attribute EventHandler oncopy ;
attribute EventHandler oncuechange ;
attribute EventHandler oncut ;
attribute EventHandler ondblclick ;
attribute EventHandler ondrag ;
attribute EventHandler ondragend ;
attribute EventHandler ondragenter ;
attribute EventHandler ondragleave ;
attribute EventHandler ondragover ;
attribute EventHandler ondragstart ;
attribute EventHandler ondrop ;
attribute EventHandler ondurationchange ;
attribute EventHandler onemptied ;
attribute EventHandler onended ;
attribute OnErrorEventHandler onerror ;
attribute EventHandler onfocus ;
attribute EventHandler onformdata ;
attribute EventHandler oninput ;
attribute EventHandler oninvalid ;
attribute EventHandler onkeydown ;
attribute EventHandler onkeypress ;
attribute EventHandler onkeyup ;
attribute EventHandler onload ;
attribute EventHandler onloadeddata ;
attribute EventHandler onloadedmetadata ;
attribute EventHandler onloadstart ;
attribute EventHandler onmousedown ;
[LegacyLenientThis ] attribute EventHandler onmouseenter ;
[LegacyLenientThis ] attribute EventHandler onmouseleave ;
attribute EventHandler onmousemove ;
attribute EventHandler onmouseout ;
attribute EventHandler onmouseover ;
attribute EventHandler onmouseup ;
attribute EventHandler onpaste ;
attribute EventHandler onpause ;
attribute EventHandler onplay ;
attribute EventHandler onplaying ;
attribute EventHandler onprogress ;
attribute EventHandler onratechange ;
attribute EventHandler onreset ;
attribute EventHandler onresize ;
attribute EventHandler onscroll ;
attribute EventHandler onscrollend ;
attribute EventHandler onsecuritypolicyviolation ;
attribute EventHandler onseeked ;
attribute EventHandler onseeking ;
attribute EventHandler onselect ;
attribute EventHandler onslotchange ;
attribute EventHandler onstalled ;
attribute EventHandler onsubmit ;
attribute EventHandler onsuspend ;
attribute EventHandler ontimeupdate ;
attribute EventHandler ontoggle ;
attribute EventHandler onvolumechange ;
attribute EventHandler onwaiting ;
attribute EventHandler onwebkitanimationend ;
attribute EventHandler onwebkitanimationiteration ;
attribute EventHandler onwebkitanimationstart ;
attribute EventHandler onwebkittransitionend ;
attribute EventHandler onwheel ;
};
interface mixin WindowEventHandlers {
attribute EventHandler onafterprint ;
attribute EventHandler onbeforeprint ;
attribute OnBeforeUnloadEventHandler onbeforeunload ;
attribute EventHandler onhashchange ;
attribute EventHandler onlanguagechange ;
attribute EventHandler onmessage ;
attribute EventHandler onmessageerror ;
attribute EventHandler onoffline ;
attribute EventHandler ononline ;
attribute EventHandler onpagehide ;
attribute EventHandler onpagereveal ;
attribute EventHandler onpageshow ;
attribute EventHandler onpageswap ;
attribute EventHandler onpopstate ;
attribute EventHandler onrejectionhandled ;
attribute EventHandler onstorage ;
attribute EventHandler onunhandledrejection ;
attribute EventHandler onunload ;
};
特定の操作やメソッドは、要素上でイベントを発火させるように定義されています。例えば、click()
メソッドは HTMLElement インターフェイス上で、要素上で click
イベントを発火させるように定義されています。[UIEVENTS]
名前が e の合成ポインターイベントを target に発火させる ことは、次のステップを実行することを意味します:
event を イベントを作成する ことにより取得します。PointerEvent
を使用します。
event の type
属性を e に初期化します。
event の bubbles
と cancelable
属性を true に初期化します。
event の composed flag を設定します。
not trusted flag が設定されている場合、event の isTrusted
属性を false に初期化します。
event の ctrlKey、shiftKey、altKey、および
metaKey 属性を、現在のキー入力デバイスの状態に応じて初期化します(利用できないキーは false)。
event の view
属性を、target の ノードドキュメント
の Window オブジェクトに初期化します。もし存在しない場合は null にします。
event の getModifierState() メソッドが、キー入力デバイスの現在の状態を適切に説明する値を返すようにします。
event を target に対して ディスパッチする 結果を返します。
click イベントを発火させる ことは、target に対して 名前が click
の合成ポインターイベントを発火させる ことを意味します。
WindowOrWorkerGlobalScope
ミキシンWindowOrWorkerGlobalScope
ミキシンは、Window および WorkerGlobalScope
オブジェクト上で公開されるAPIに使用されます。
他の標準は、partial interface mixin WindowOrWorkerGlobalScope { … };
を使用してさらに拡張し、適切な参照を追加することが推奨されます。
typedef (DOMString or Function or TrustedScript ) TimerHandler ;
interface mixin WindowOrWorkerGlobalScope {
[Replaceable ] readonly attribute USVString origin ;
readonly attribute boolean isSecureContext ;
readonly attribute boolean crossOriginIsolated ;
undefined reportError (any e );
// base64 utility methods
DOMString btoa (DOMString data );
ByteString atob (DOMString data );
// timers
long setTimeout (TimerHandler handler , optional long timeout = 0, any ... arguments );
undefined clearTimeout (optional long id = 0);
long setInterval (TimerHandler handler , optional long timeout = 0, any ... arguments );
undefined clearInterval (optional long id = 0);
// microtask queuing
undefined queueMicrotask (VoidFunction callback );
// ImageBitmap
Promise <ImageBitmap > createImageBitmap (ImageBitmapSource image , optional ImageBitmapOptions options = {});
Promise <ImageBitmap > createImageBitmap (ImageBitmapSource image , long sx , long sy , long sw , long sh , optional ImageBitmapOptions options = {});
// structured cloning
any structuredClone (any value , optional StructuredSerializeOptions options = {});
};
Window includes WindowOrWorkerGlobalScope ;
WorkerGlobalScope includes WindowOrWorkerGlobalScope ;
self.isSecureContext
全ての現在のエンジンでサポートされています。
このグローバルオブジェクトがセキュアコンテキストを表しているかどうかを返します。 [SECURE-CONTEXTS]
self.origin
全ての現在のエンジンでサポートされています。
グローバルオブジェクトの起源を、文字列としてシリアライズして返します。
self.crossOriginIsolated
全ての現在のエンジンでサポートされています。
このグローバルで実行されているスクリプトが、クロスオリジン隔離を必要とするAPIを使用することが許可されているかどうかを返します。これは、`Cross-Origin-Opener-Policy`
と
`Cross-Origin-Embedder-Policy`
HTTP応答ヘッダー、および"cross-origin-isolated"
機能に依存します。
開発者には、self.originの使用が強く推奨されます。
location.originよりも。
前者は環境の起源を返し、
後者は環境のURLを返します。次のスクリプトが
https://stargate.example/のドキュメントで実行されることを想像してください:
var frame = document. createElement( "iframe" )
frame. onload = function () {
var frameWin = frame. contentWindow
console. log( frameWin. location. origin) // "null"
console. log( frameWin. origin) // "https://stargate.example"
}
document. body. appendChild( frame)
self.origin は、より信頼性の高いセキュリティインジケーターです。
isSecureContext のゲッター手順は、this の 関連設定オブジェクト が
セキュアコンテキスト である場合に
true を返し、それ以外の場合は false を返します。
origin
のゲッター手順は、this の
関連設定オブジェクト の
オリジン を シリアライズ された形式で返します。
crossOriginIsolated のゲッター手順は、this の 関連設定オブジェクト の
クロスオリジンアイソレーテッド機能
を返します。
atob()およびbtoa()メソッドは、開発者がコンテンツをBase64エンコーディングに変換したり、その逆に変換したりすることを可能にします。
これらのAPIでは、覚えやすくするために、「b」は「バイナリ」を、「a」は「ASCII」を表すと考えることができます。ただし、実際には、主に歴史的な理由から、これらの関数の入力と出力はUnicode文字列です。
result = self.btoa(data)
すべての現在のエンジンでサポートされています。
Unicode文字列形式の入力データを受け取り、その各文字がそれぞれ値0x00から0xFFのバイナリバイトを表す範囲U+0000からU+00FF内に収まるように、入力データをBase64表現に変換し、結果を返します。
入力文字列に範囲外の文字が含まれている場合は、"InvalidCharacterError" DOMException例外をスローします。
result = self.atob(data)
すべての現在のエンジンでサポートされています。
Base64エンコードされたバイナリデータを含むUnicode文字列形式の入力データを受け取り、それをデコードして、対応するバイナリデータを表すU+0000からU+00FFの範囲内の文字からなる文字列を返します。
入力文字列が有効なBase64データでない場合は、"InvalidCharacterError" DOMExceptionをスローします。
btoa(data)メソッドは、dataにU+00FFを超えるコードポイントを持つ文字が含まれている場合、"InvalidCharacterError" DOMExceptionをスローしなければなりません。それ以外の場合、ユーザーエージェントはdataをn番目のコードポイントの8ビット表現がn番目のバイトとなるバイトシーケンスに変換し、次にそのバイトシーケンスにforgiving-base64 encodeを適用して結果を返さなければなりません。
atob(data)メソッドの手順は以下の通りです。
decodedDataを、dataにforgiving-base64 decodeを適用した結果とします。
もしdecodedDataが失敗した場合は、"InvalidCharacterError" DOMExceptionをスローします。
decodedDataを返します。
ドキュメントに動的にマークアップを挿入するためのAPIはパーサーと相互作用するため、それらの動作はHTMLドキュメント(およびHTMLパーサー) とXMLドキュメント(およびXMLパーサー)で使用されるかどうかによって異なります。
Documentオブジェクトには、動的マークアップ挿入時の例外カウンターがあり、
これはトークンに対する要素の作成
アルゴリズムと併用されて、
カスタム要素のコンストラクターが
パーサーによって呼び出されたときに、document.open()、
document.close()、
およびdocument.write()を使用できないようにするために使用されます。
初期状態では、カウンターはゼロに設定されなければなりません。
document = document.open()
すべての現在のエンジンでサポートされています。
Documentを、その場で新しいDocumentオブジェクトとして置き換えますが、以前のオブジェクトを再利用して、その結果が返されます。
結果として得られるDocumentには、HTMLパーサーが関連付けられており、document.write()を使用して解析するデータを与えることができます。
このメソッドは、Documentがまだ解析中の場合は効果がありません。
DocumentがXMLドキュメントである場合は、"InvalidStateError" DOMException例外がスローされます。
パーサーが現在カスタム要素のコンストラクターを実行している場合は、"InvalidStateError" DOMException例外がスローされます。
window = document.open(url, name, features)
window.open()メソッドのように動作します。
Documentオブジェクトには、アクティブパーサーが中止されたというブール値があり、これはドキュメントのアクティブパーサーが中止された後、スクリプトがdocument.open()およびdocument.write()メソッドを(直接的または間接的に)呼び出すのを防ぐために使用されます。初期状態では、この値はfalseです。
documentを与えられた場合のdocument open stepsは、次の通りです:
documentがXMLドキュメントである場合、"InvalidStateError" DOMException例外がスローされます。
documentの動的マークアップ挿入時の例外カウンターが0より大きい場合は、"InvalidStateError" DOMException例外をスローします。
entryDocumentを、エントリーグローバルオブジェクトの関連するDocumentとします。
documentのオリジンが、entryDocumentのオリジンと同一オリジンでない場合は、"SecurityError" DOMException例外をスローします。
documentにアクティブパーサーがあり、そのスクリプトネストレベルが0より大きい場合は、documentを返します。
これにより、インラインスクリプトが解析中にdocument.open()を呼び出しても無視されますが、タイマーコールバックやイベントハンドラーなどの非パーサータスクから呼び出された場合には効果が発生します。
同様に、documentのアンロードカウンターが0より大きい場合は、documentを返します。
これにより、document.open()がbeforeunload、pagehide、またはunloadイベントハンドラーからドキュメントがアンロードされている最中に呼び出された場合、無視されることになります。
documentのアクティブパーサーが中止されたがtrueである場合は、documentを返します。
これにより、ナビゲーションが開始された後、特に初期解析中にdocument.open()が呼び出された場合に無視されます。詳細についてはissue #4723を参照してください。
documentのノードナビゲーブルがnullでなく、documentのノードナビゲーブルの進行中のナビゲーションがナビゲーションIDである場合は、documentのノードナビゲーブルの読み込みを停止します。
documentのシャドウを含む包括的な子孫の各nodeに対して、nodeに与えられたすべてのイベントリスナーとハンドラーを消去します。
documentがdocumentの関連するDocumentである場合は、documentの関連するグローバルオブジェクトに与えられたすべてのイベントリスナーとハンドラーを消去します。
すべてを置き換えるをdocument内でnullにします。
documentが完全にアクティブである場合は、次の操作を行います。
newURLをentryDocumentのURLのコピーとします。
entryDocumentがdocumentでない場合は、newURLのフラグメントをnullに設定します。
documentとnewURLを使用してURLと履歴の更新手順を実行します。
documentの初期about:blankをfalseに設定します。
documentの進行中のiframeロードフラグが設定されている場合は、documentのiframeロードをミュートフラグを設定します。
documentをノークイクスモードに設定します。
新しいHTMLパーサーを作成し、documentに関連付けます。これはスクリプト作成パーサーです(つまり、document.open()およびdocument.close()メソッドによって閉じることができ、トークナイザーはdocument.close()を明示的に呼び出すまでEOFトークンを出力しません)。エンコーディングの確信度は無関係です。
documentの現在のドキュメント準備状況を更新して、「loading」にします。
これにより、readystatechangeイベントが発生しますが、以前のステップで観察する可能性のあるイベントリスナーとハンドラーを消去したため、著者コードには実際には観察できません。
documentを返します。
document open
stepsは、Documentがポストロードタスクの準備ができているか、完全にロードされたかどうかに影響を与えません。
open(unused1,
unused2)メソッドは、document open stepsをthisで実行した結果を返さなければなりません。
unused1およびunused2引数は無視されますが、1つまたは2つの引数で関数を呼び出すコードが引き続き動作するようにIDLに残されています。これは、Web IDLのオーバーロード解決アルゴリズムのルールにより、引数がないとそのような呼び出しに対してTypeError例外がスローされるためです。whatwg/webidl issue
#581は、それらの削除を可能にするためのアルゴリズムの変更を調査しています。[WEBIDL]
open(url,
name, features)メソッドは、次の手順を実行する必要があります。
thisが完全にアクティブでない場合は、"InvalidAccessError" DOMException例外をスローします。
url、name、およびfeaturesを使用してウィンドウオープン手順を実行した結果を返します。
document.close()
すべての現在のエンジンでサポートされています。
document.open()メソッドで開かれた入力ストリームを閉じます。
DocumentがXMLドキュメントである場合は、"InvalidStateError" DOMException例外をスローします。
パーサーが現在カスタム要素のコンストラクターを実行している場合は、"InvalidStateError" DOMException例外をスローします。
close()メソッドは、次の手順を実行する必要があります。
thisがXMLドキュメントである場合、"InvalidStateError" DOMException例外をスローします。
thisの動的マークアップ挿入時の例外カウンターが0より大きい場合は、"InvalidStateError" DOMException例外をスローします。
スクリプト作成パーサーがthisに関連付けられていない場合、何もしないで返します。
パーサーの入力ストリームの終わりに明示的な「EOF」キャラクターを挿入します。
thisの保留中の解析ブロックスクリプトがnullでない場合、何もしないで返します。
トークナイザーを実行し、トークナイザーが明示的な「EOF」キャラクターに達するか、イベントループをスピンするまでトークンを処理します。
document.write()document.write(...text)
すべての現在のエンジンでサポートされています。
一般的に、指定された文字列をDocumentの入力ストリームに追加します。
このメソッドは非常に独特な挙動を示します。場合によっては、このメソッドが実行中のHTMLパーサーの状態に影響を与え、ドキュメントに対応しないDOMが生成されることがあります(例えば、書き込まれた文字列が"<plaintext>"や"<!--"の場合)。他の場合では、document.open()が呼び出されたかのように、ページ全体がクリアされることがあります。また、このメソッドが単に無視される、あるいは例外をスローすることもあります。ユーザーエージェントは、このメソッドを介して挿入されたscript要素の実行を明示的に回避することが許可されています。さらに悪いことに、このメソッドの正確な動作はネットワーク遅延に依存することがあり、その結果、デバッグが非常に困難な失敗を引き起こす可能性があります。これらすべての理由から、このメソッドの使用は強く推奨されません。
XMLドキュメントに対して呼び出された場合、"InvalidStateError" DOMExceptionをスローします。
パーサーが現在カスタム要素のコンストラクターを実行している場合、"InvalidStateError" DOMExceptionがスローされます。
このメソッドは、scriptやイベントハンドラーコンテンツ属性などの潜在的に危険な要素や属性を削除するためのサニタイズを行いません。
Documentオブジェクトには、破壊的書き込みを無視するカウンターがあり、これはscript要素の処理と併用され、外部スクリプトがdocument.write()を使用してdocument.open()を暗黙的に呼び出すことによってドキュメントを破壊できないようにするために使用されます。初期状態では、このカウンターはゼロに設定されなければなりません。
documentというDocumentオブジェクト、リストtext、ブール値lineFeed、および文字列sinkが与えられた場合のdocument write stepsは、次の通りです:
stringを空の文字列にします。
textが文字列を含む場合はisTrustedをfalseに、それ以外の場合はtrueに設定します。
textのvalueごとに次の操作を行います:
valueがTrustedHTMLオブジェクトである場合、その関連するデータをstringに追加します。
それ以外の場合、valueをstringに追加します。
isTrustedがfalseである場合、TrustedHTML、thisの関連するグローバルオブジェクト、string、sink、および"script"を使用してTrusted
Type対応文字列取得アルゴリズムを呼び出した結果をstringに設定します。
lineFeedがtrueである場合、U+000A LINE FEEDをstringに追加します。
documentがXMLドキュメントである場合、"InvalidStateError" DOMExceptionをスローします。
documentの動的マークアップ挿入時の例外カウンターが0より大きい場合、"InvalidStateError" DOMExceptionをスローします。
documentのアクティブパーサーが中止されたがtrueである場合、何もせずに返します。
挿入ポイントが未定義である場合、次の操作を行います:
documentのアンロードカウンターが0より大きい場合、またはdocumentの破壊的書き込みを無視するカウンターが0より大きい場合、何もせずに返します。
documentを使用してdocument open stepsを実行します。
documentの保留中の解析ブロックスクリプトがnullの場合、HTMLパーサーによりstringを1コードポイントずつ処理し、トークナイザーが挿入ポイントに達するか、ツリー構築段階でトークナイザーによる処理が中止されるまでトークンを処理します(これはトークナイザーがscriptの終了タグトークンを生成した場合に発生する可能性があります)。
もしdocument.write()メソッドがインラインで実行されるスクリプト(すなわち、パーサーがscriptタグを解析したために実行されるスクリプト)から呼び出された場合、これはパーサーの再入呼び出しです。パーサー一時停止フラグが設定されている場合、トークナイザーは直ちに中止し、トークナイザーのパーサー一時停止フラグチェックに従って、HTMLは解析されません。
document.write(...text)メソッドの手順は、this、text、false、および"Document write"を使用してdocument write stepsを実行することです。
document.writeln()document.writeln(...text)
すべての現在のエンジンでサポートされています。
指定された文字列をDocumentの入力ストリームに追加し、その後に改行文字を追加します。必要に応じて、最初にopen()メソッドを暗黙的に呼び出します。
XMLドキュメントで呼び出された場合は、"InvalidStateError" DOMExceptionをスローします。
パーサーが現在カスタム要素のコンストラクターを実行している場合は、"InvalidStateError" DOMExceptionをスローします。
このメソッドは、scriptやイベントハンドラーコンテンツ属性のような潜在的に危険な要素や属性を削除するためのサニタイズを行いません。
document.writeln(...text)メソッドの手順は、this、text、true、および"Document writeln"を使用してdocument write stepsを実行することです。
すべての現在のエンジンでサポートされています。
partial interface Element {
[CEReactions ] undefined setHTMLUnsafe ((TrustedHTML or DOMString ) html );
DOMString getHTML (optional GetHTMLOptions options = {});
[CEReactions ] attribute (TrustedHTML or [LegacyNullToEmptyString ] DOMString ) innerHTML ;
[CEReactions ] attribute (TrustedHTML or [LegacyNullToEmptyString ] DOMString ) outerHTML ;
[CEReactions ] undefined insertAdjacentHTML (DOMString position , (TrustedHTML or DOMString ) string );
};
partial interface ShadowRoot {
[CEReactions ] undefined setHTMLUnsafe ((TrustedHTML or DOMString ) html );
DOMString getHTML (optional GetHTMLOptions options = {});
[CEReactions ] attribute (TrustedHTML or [LegacyNullToEmptyString ] DOMString ) innerHTML ;
};
dictionary GetHTMLOptions {
boolean serializableShadowRoots = false ;
sequence <ShadowRoot > shadowRoots = [];
};
DOMParserインターフェイスDOMParserインターフェイスは、文字列をHTMLまたはXMLとして解析することで、新しいDocumentオブジェクトを作成できるようにします。
parser = new DOMParser()
すべての現在のエンジンでサポートされています。
新しいDOMParserオブジェクトを構築します。
document = parser.parseFromString(string, type)
すべての現在のエンジンでサポートされています。
typeに応じて、stringをHTMLまたはXMLパーサーで解析し、結果として得られるDocumentを返します。typeには"text/html"(HTMLパーサーを呼び出す)や、"text/xml"、"application/xml"、"application/xhtml+xml"、"image/svg+xml"(XMLパーサーを呼び出す)のいずれかを指定できます。
XMLパーサーの場合、stringが解析できない場合、返されるDocumentには、結果として得られるエラーを示す要素が含まれます。
解析中にscript要素は評価されず、結果として得られるドキュメントのエンコーディングは常にUTF-8になります。ドキュメントのURLはparserの関連するグローバルオブジェクトから継承されます。
上記以外のtypeの値を指定すると、TypeError例外がスローされます。
DOMParserが、クラスとして構築され、そのparseFromString()メソッドが呼び出される必要があるという設計は、不幸な歴史的遺物です。この機能を今日設計しているのであれば、これはスタンドアロン関数になるでしょう。HTMLを解析する場合、現代的な代替手段はDocument.parseHTMLUnsafe()です。
このメソッドは、scriptやイベントハンドラーコンテンツ属性のような潜在的に危険な要素や属性を削除するためのサニタイズを行いません。
[Exposed =Window ]
interface DOMParser {
constructor ();
[NewObject ] Document parseFromString ((TrustedHTML or DOMString ) string , DOMParserSupportedType type );
};
enum DOMParserSupportedType {
" text/html " ,
" text/xml " ,
" application/xml " ,
" application/xhtml+xml " ,
" image/svg+xml "
};
new DOMParser()コンストラクタの手順は、何も行わないことです。
parseFromString(string, type)メソッドの手順は次のとおりです:
compliantStringを、TrustedHTML、thisの関連するグローバルオブジェクト、string、"DOMParser parseFromString"および"script"を用いてTrusted
Type対応文字列取得アルゴリズムを呼び出した結果として得ます。
新しいdocumentを作成します。Documentで、コンテンツタイプはtypeであり、URLは、thisの関連するグローバルオブジェクトの関連するDocumentのURLになります。
ドキュメントのエンコーディングはデフォルトのUTF-8のままにされます。特に、compliantStringの解析中に見つかったXML宣言やmeta要素は、エンコーディングに影響を与えません。
typeに基づいてスイッチします:
text/html"
documentとcompliantStringを指定して、文字列からHTMLを解析します。
documentにはブラウジングコンテキストがないため、スクリプティングは無効です。
documentに関連付けられたparserを用いて、XMLパーサーを作成し、XMLスクリプティングサポートを無効化します。
parserを使用してcompliantStringを解析します。
前の手順でXMLの整形式またはXML名前空間の整形式エラーが発生した場合は:
documentを返します。
文字列からHTMLを解析するには、Documentのdocumentと文字列のhtmlを指定します:
documentのタイプを"html"に設定します。
documentに関連付けられたparserを用いて、HTMLパーサーを作成します。
parserを起動し、入力ストリームに挿入されたすべての文字を消費するまで実行します。
この操作により、ドキュメントのモードが変更される可能性があります。
element.setHTMLUnsafe(html)
htmlをHTMLパーサーを使用して解析し、その結果でelementの子を置き換えます。elementはHTMLパーサーにコンテキストを提供します。
shadowRoot.setHTMLUnsafe(html)
htmlをHTMLパーサーを使用して解析し、その結果でshadowRootの子を置き換えます。shadowRootのホストはHTMLパーサーにコンテキストを提供します。
doc = Document.parseHTMLUnsafe(html)
htmlをHTMLパーサーを使用して解析し、結果として得られるDocumentを返します。
script要素は解析中に評価されず、結果として得られるドキュメントのエンコーディングは常にUTF-8になります。ドキュメントのURLはabout:blankになります。
これらのメソッドは、scriptやイベントハンドラーコンテンツ属性のような潜在的に危険な要素や属性を削除するためのサニタイズを行いません。
ElementのsetHTMLUnsafe(html)メソッドの手順は次のとおりです:
compliantHTMLを、TrustedHTML、thisの関連するグローバルオブジェクト、html、"Element setHTMLUnsafe"および"script"を用いてTrusted
Type対応文字列取得アルゴリズムを呼び出した結果として得ます。
targetを、thisがtemplate要素である場合はテンプレートのコンテンツ、それ以外の場合はthisに設定します。
ShadowRootのsetHTMLUnsafe(html)メソッドの手順は次のとおりです:
compliantHTMLを、TrustedHTML、thisの関連するグローバルオブジェクト、html、"ShadowRoot setHTMLUnsafe"および"script"を用いてTrusted
Type対応文字列取得アルゴリズムを呼び出した結果として得ます。
危険なHTML設定には、ElementまたはDocumentFragmentのtarget、ElementのcontextElement、および文字列のhtmlを指定します:
newChildrenをHTMLフラグメント解析アルゴリズムを用いて、contextElement、html、およびtrueを指定して得ます。
fragmentを新しいDocumentFragmentにし、そのノードドキュメントはcontextElementのノードドキュメントとします。
newChildrenの各nodeについて、追加をfragmentに行います。
すべてを置換をfragmentとtargetに対して行います。
静的なparseHTMLUnsafe(html)メソッドの手順は次のとおりです:
compliantHTMLを、TrustedHTML、thisの関連するグローバルオブジェクト、html、"Document parseHTMLUnsafe"および"script"を用いてTrusted
Type対応文字列取得アルゴリズムを呼び出した結果として得ます。
documentを、コンテンツタイプが"text/html"である新しいDocumentとして作成します。
documentにはブラウジングコンテキストがないため、スクリプティングは無効です。
documentの宣言的シャドウルートを許可をtrueに設定します。
文字列からHTMLを解析するを、documentとcompliantHTMLを指定して実行します。
documentを返します。
html = element.getHTML({ serializableShadowRoots, shadowRoots })
elementをHTMLにシリアル化した結果を返します。element内のシャドウルートは、指定されたオプションに従ってシリアル化されます:
serializableShadowRootsがtrueの場合、シリアル化可能としてマークされたすべてのシャドウルートがシリアル化されます。
shadowRoots配列が指定された場合、その配列内のすべてのシャドウルートがシリアル化されます。これはシリアル化可能としてマークされているかどうかに関係なく行われます。
いずれのオプションも指定されない場合、シャドウルートはシリアル化されません。
html = shadowRoot.getHTML({ serializableShadowRoots, shadowRoots })
shadowRootをHTMLにシリアル化した結果を返します。シャドウホストがコンテキスト要素として使用されます。shadowRoot内のシャドウルートは、上記のオプションに従ってシリアル化されます。
ElementのgetHTML(options)メソッドの手順は、HTMLフラグメントシリアル化アルゴリズムの結果を返すことです。this、options["serializableShadowRoots"]、およびoptions["shadowRoots"]を使用して実行されます。
ShadowRootのgetHTML(options)メソッドの手順は、HTMLフラグメントシリアル化アルゴリズムの結果を返すことです。this、options["serializableShadowRoots"]、およびoptions["shadowRoots"]を使用して実行されます。
innerHTML
プロパティinnerHTMLプロパティには、「DOM
Parsing and Serialization」のissueトラッカーで、その仕様に関する様々な問題を記録した複数の未解決の問題があります。
element.innerHTML
要素の内容を表すHTMLまたはXMLのフラグメントを返します。
XMLドキュメントの場合、要素がXMLにシリアル化できない場合は"InvalidStateError"DOMExceptionをスローします。
element.innerHTML = value
指定された文字列から解析されたノードで要素の内容を置き換えます。
XMLドキュメントの場合、指定された文字列が適切に形成されていない場合は"SyntaxError"DOMExceptionをスローします。
shadowRoot.innerHTML
シャドウルートの内容を表すHTMLフラグメントを返します。
shadowRoot.innerHTML = value
指定された文字列から解析されたノードでシャドウルートの内容を置き換えます。
これらのプロパティのセッターは、scriptやイベントハンドラーコンテンツ属性のような潜在的に危険な要素や属性を削除するサニタイズを行いません。
フラグメントシリアル化アルゴリズムの手順は、Element、Document、またはDocumentFragmentnodeとブール値require
well-formedを与えた場合に、次の手順を実行します:
context documentをnodeのノードドキュメントとします。
context documentがHTMLドキュメントである場合、node、false、および「」を用いてHTMLフラグメントシリアル化アルゴリズムの結果を返します。
require well-formedを指定して、nodeのXMLシリアル化を返します。
フラグメント解析アルゴリズムの手順は、Elementcontextと文字列markupを与えた場合に、次の手順を実行します:
algorithmをHTMLフラグメント解析アルゴリズムとします。
contextのノードドキュメントがXMLドキュメントである場合、algorithmをXMLフラグメント解析アルゴリズムに設定します。
new childrenをmarkupを与えてalgorithmを実行した結果とし、contextをcontextに設定します。
fragmentを、新しいDocumentFragmentとし、そのノードドキュメントをcontextのノードドキュメントに設定します。
fragmentを返します。
ElementのinnerHTMLゲッターの手順は、フラグメントシリアル化アルゴリズムの手順を実行し、その結果を返すことです。thisとtrueを使用して実行します。
ShadowRootのinnerHTMLゲッターの手順は、フラグメントシリアル化アルゴリズムの手順を実行し、その結果を返すことです。thisとtrueを使用して実行します。
ElementのinnerHTMLセッターの手順は次のとおりです:
compliantStringを、TrustedHTML、thisの関連グローバルオブジェクト、指定された値、"Element innerHTML"、および"script"を使用してGet Trusted
Type compliant stringアルゴリズムを実行した結果とします。
contextをthisとします。
fragmentをcontextとcompliantStringを用いてフラグメント解析アルゴリズムの手順を実行した結果とします。
contextがtemplate要素である場合、contextをtemplate要素のテンプレート内容(DocumentFragment)に設定します。
innerHTMLをtemplate要素に設定すると、その子要素ではなく、テンプレート内容のすべてのノードが置き換えられます。
context内でfragmentを用いてすべて置き換えを行います。
ShadowRootのinnerHTMLセッターの手順は次のとおりです:
compliantStringを、TrustedHTML、thisの関連グローバルオブジェクト、指定された値、"ShadowRoot innerHTML"、および"script"を使用してGet Trusted
Type compliant stringアルゴリズムを実行した結果とします。
fragmentをcontextとcompliantStringを用いてフラグメント解析アルゴリズムの手順を実行した結果とします。
outerHTML
プロパティouterHTMLプロパティには、「DOM
Parsing and Serialization」のissueトラッカーで、その仕様に関する様々な問題を記録した複数の未解決の問題があります。
element.outerHTML
要素およびその内容を表すHTMLまたはXMLのフラグメントを返します。
XMLドキュメントの場合、要素がXMLにシリアル化できない場合は"InvalidStateError"DOMExceptionをスローします。
element.outerHTML = value
指定された文字列から解析されたノードで要素を置き換えます。
XMLドキュメントの場合、指定された文字列が適切に形成されていない場合は"SyntaxError"DOMExceptionをスローします。
要素の親がDocumentである場合、"NoModificationAllowedError"DOMExceptionをスローします。
このプロパティのセッターは、scriptやイベントハンドラーコンテンツ属性のような潜在的に危険な要素や属性を削除するサニタイズを行いません。
ElementのouterHTMLゲッターの手順は次のとおりです:
elementを、その唯一の子がthisである仮想ノードとします。
elementとtrueを使用してフラグメントシリアル化アルゴリズムの手順を実行した結果を返します。
ElementのouterHTMLセッターの手順は次のとおりです:
compliantStringを、TrustedHTML、thisの関連グローバルオブジェクト、指定された値、"Element outerHTML"、および"script"を使用してGet Trusted
Type compliant stringアルゴリズムを実行した結果とします。
parentがnullの場合は、returnします。この後の手順を実行しても、作成されたノードへの参照を取得する方法がないためです。
parentがDocumentである場合、"NoModificationAllowedError"DOMExceptionをスローします。
parentがDocumentFragmentである場合、parentをthisのノードドキュメント、body、およびHTML名前空間を指定して要素を作成する結果に設定します。
fragmentをparentとcompliantStringを用いてフラグメント解析アルゴリズムの手順を実行した結果とします。
insertAdjacentHTML()
メソッドinsertAdjacentHTML()
メソッドは、DOM Parsing and Serializationの問題追跡システムに多くの未解決の問題があり、仕様に関するさまざまな問題が文書化されています。
element.insertAdjacentHTML(position, string)
stringをHTMLまたはXMLとして解析し、position引数で指定された位置にツリー内のノードを挿入します。具体的には、次のようになります。
beforebegin"
afterbegin"
beforeend"
afterend"
"SyntaxError" DOMException
をスローします。引数が無効な値を持つ場合(例:XMLドキュメントの場合、
指定された文字列が正しく整形されていない場合など)。
"NoModificationAllowedError"
DOMException
をスローします。指定された位置が可能でない場合(例:Documentの
ルート要素の後に要素を挿入する場合)。
このメソッドのセッターは、script
や イベントハンドラコンテンツ属性
のような潜在的に危険な要素や属性を削除するためのサニタイズを行いません。
Elementの
insertAdjacentHTML(position,
string)メソッドの手順は以下の通りです:
compliantString を次のアルゴリズムを使用して呼び出した結果に設定します: Trusted Type
準拠の文字列を取得する アルゴリズムを TrustedHTML、
this の 関連するグローバルオブジェクト、string、
"Element insertAdjacentHTML"、および "script" で設定します。
context を null に設定します。
このリストから最初に一致する項目を使用します:
beforebegin" に対する ASCII
大文字小文字を区別しない 一致である場合
afterend" に対する ASCII
大文字小文字を区別しない 一致である場合
もし context が null または Document
である場合は、
"NoModificationAllowedError"
DOMException
を投げます。
afterbegin" に対する ASCII
大文字小文字を区別しない 一致である場合
beforeend" に対する ASCII
大文字小文字を区別しない 一致である場合
"SyntaxError" DOMException
を投げます。
もし context が Element
ではない場合、
または次のすべてが真である場合:
context を次の結果に設定します: 要素を作成する
this の ノード文書、body、および
HTML名前空間
を与えて作成します。
fragment を フラグメント解析アルゴリズムの手順 を context と compliantString で呼び出した結果に設定します。
beforebegin" に対する ASCII
大文字小文字を区別しない 一致である場合
afterend" に対する ASCII
大文字小文字を区別しない 一致である場合
afterbegin" に対する ASCII
大文字小文字を区別しない 一致である場合
beforeend" に対する ASCII
大文字小文字を区別しない 一致である場合
他の直接的なNode操作APIと同様に(innerHTMLとは異なり)、
insertAdjacentHTML()
はtemplate要素に対する
特別な処理を含んでいません。ほとんどの場合、
templateEl.content.insertAdjacentHTML()
を使用して、template
要素の子ノードを直接操作するのではなく、操作します。
createContextualFragment()
メソッドcreateContextualFragment()
メソッドには、DOM Parsing and Serializationのissue
trackerに多数の未解決の問題が記録されており、その仕様に関するさまざまな問題が文書化されています。
docFragment = range.createContextualFragment(string)
指定されたマークアップ文字列stringから作成されたDocumentFragmentを返します。この操作は、rangeの開始ノードを解析時のコンテキストとして使用して行われます。
このメソッドは、script要素やイベントハンドラー属性のような潜在的に危険な要素や属性を削除するためのサニタイズを行いません。
partial interface Range {
[CEReactions , NewObject ] DocumentFragment createContextualFragment ((TrustedHTML or DOMString ) string );
};
Rangeの
createContextualFragment(string)
メソッドの手順は次の通りです:
compliantStringを取得します。これは、Trusted Type準拠の文字列取得アルゴリズムを使用して、TrustedHTML、
thisの関連するグローバルオブジェクト、string、および"Range
createContextualFragment"を使用して得られる結果です。
elementをnullに設定します。
もしnodeがElementを
実装している場合、elementをnodeに設定します。
それ以外の場合、もしnodeがTextまたは
Commentを
実装している場合、elementをnodeの親要素に設定します。
もしelementがnullまたは以下のすべてが真である場合:
その場合、elementを次のようにして取得します:要素を作成し、thisのノードドキュメント、
body、
およびHTML名前空間を
与えます。
fragment nodeを取得します。これはフラグメント解析 アルゴリズムの手順を使用して、elementとcompliantStringを 与えて得られる結果です。
それぞれのfragment nodeのscript要素の
子孫に対して:
scriptの既に開始されたフラグを falseに設定します。
scriptのパーサードキュメントを nullに設定します。
fragment nodeを返します。
setTimeout() および setInterval()
メソッドは、タイマーに基づいたコールバックをスケジュールするための手段を提供します。
id = self.setTimeout(handler [, timeout [, ...arguments ] ])
現在のすべてのエンジンでサポートされています。
handlerをtimeoutミリ秒後に実行するようにタイムアウトをスケジュールします。任意のargumentsはhandlerに直接渡されます。
id = self.setTimeout(code [, timeout ])
codeをtimeoutミリ秒後にコンパイルして実行するようにタイムアウトをスケジュールします。
self.clearTimeout(id)
現在のすべてのエンジンでサポートされています。
idで識別されるsetTimeout() または
setInterval()
で設定されたタイムアウトをキャンセルします。
id = self.setInterval(handler [, timeout [, ...arguments ] ])
現在のすべてのエンジンでサポートされています。
handlerをtimeoutミリ秒ごとに実行するようにタイムアウトをスケジュールします。任意のargumentsはhandlerに直接渡されます。
id = self.setInterval(code [, timeout ])
codeをtimeoutミリ秒ごとにコンパイルして実行するようにタイムアウトをスケジュールします。
self.clearInterval(id)
現在のすべてのエンジンでサポートされています。
idで識別されるsetInterval()
または
setTimeout()で設定されたタイムアウトをキャンセルします。
タイマーはネスト可能です。ただし、5つ以上のネストされたタイマーがある場合、間隔は最低4ミリ秒に強制されます。
このAPIはタイマーが予定通りに正確に実行されることを保証するものではありません。CPU負荷や他のタスクなどによる遅延が予想されます。
WindowOrWorkerGlobalScope
ミックスインを実装するオブジェクトは、setTimeout および setInterval の ID のマップを持ち、これは初期状態では空の順序付きマップです。このマップ内の各キーは、setTimeout()またはsetInterval()呼び出しの戻り値に対応する正の整数です。各値はオブジェクトのアクティブなタイマーのマップ内のキーに対応する一意の内部値です。
setTimeout(handler, timeout,
...arguments) メソッドの手順は、タイマー初期化手順を、this, handler,
timeout, argumentsを使用し、falseで実行した結果を返します。
setInterval(handler, timeout,
...arguments) メソッドの手順は、タイマー初期化手順を、this, handler,
timeout, argumentsを使用し、trueで実行した結果を返します。
clearTimeout(id) と clearInterval(id) メソッドの手順は、削除することです。thisのsetTimeout および setInterval の ID
のマップ[id]を削除します。
clearTimeout()
と clearInterval()
は、同じマップからエントリを削除するため、どちらのメソッドも setTimeout()
または setInterval()
によって作成されたタイマーをクリアするために使用できます。
タイマー初期化手順を実行するために、WindowOrWorkerGlobalScope
global、文字列またはFunction、
またはTrustedScript
handler、数値のtimeout、リストのarguments、ブール値のrepeat、
そしてオプションでrepeatがtrueの場合に限り、数値のpreviousIdを与えて次の手順を実行します。これらは数値を返します。
globalがWorkerGlobalScopeオブジェクトであれば、thisArgをglobalとします。そうでなければ、thisArgをglobalに対応するWindowProxyとします。
previousIdが与えられた場合、idをpreviousIdとします。そうでなければ、idを実装定義の整数とし、それは0より大きく、globalのsetTimeoutとsetInterval IDのマップに既に存在しないものでなければなりません。
周囲のエージェントのイベントループの現在実行中のタスクが、このアルゴリズムによって作成されたタスクである場合、nesting levelをタスクのタイマーネスティングレベルとします。それ以外の場合、nesting levelを0とします。
タスクのタイマーネスティングレベルは、setTimeout()のネストされた呼び出し、およびsetInterval()によって作成された繰り返しタイマーの両方に使用されます。(あるいは、このアルゴリズムのネストされた呼び出しを表します)。
もしtimeoutが0未満である場合、timeoutを0に設定します。
もしnesting levelが5を超え、timeoutが4未満である場合、timeoutを4に設定します。
realmをglobalの関連する領域とします。
initiating scriptをアクティブスクリプトとします。
uniqueHandleをnullとします。
taskを以下のサブステップを実行するタスクとします:
もしidがglobalのsetTimeoutとsetInterval IDのマップに存在しない場合、これらの手順を中止します。
もしglobalのsetTimeoutとsetInterval IDのマップ[id]がuniqueHandleと等しくない場合、これらの手順を中止します。
これは、clearTimeout()やclearInterval()呼び出しによってIDがクリアされ、後続のsetTimeout()またはsetInterval()呼び出しによって再利用された場合に対応します。
タイマーハンドラーのタイミング情報を記録する、handler、globalの関連する設定オブジェクト、およびrepeatを指定します。
もしhandlerがFunctionである場合、コールバック関数を呼び出すことにより、argumentsを渡し、thisArgをcallback
this valueに設定してhandlerを実行します。
それ以外の場合:
previousIdが与えられていない場合:
globalNameを"Window"、thisの関連するグローバルオブジェクトがWindowオブジェクトであれば、それ以外の場合は"Worker"とします。
methodNameをrepeatがtrueの場合"setInterval"、それ以外の場合"setTimeout"とします。
sinkをglobalName、U+0020 SPACE、およびmethodNameを連結したものとします。
handlerを信頼されるタイプに準拠する文字列を取得するアルゴリズムを使用して、TrustedScript、thisの関連するグローバルオブジェクト、handler、sink、および"script"を指定して取得します。
アサート: handlerは文字列です。
EnsureCSPDoesNotBlockStringCompilationを実行します。realm、« »、handler、handler、タイマー、« »、handlerが与えられた場合、この操作が例外をスローした場合、キャッチし、それをグローバルに報告し、これらの手順を中止します。
settings objectをglobalの関連する設定オブジェクトとします。
fetch optionsをデフォルトのクラシックスクリプトフェッチオプションとします。
base URLをsettings objectのAPIベースURLとします。
もしinitiating scriptがnullでない場合:
fetch optionsを、スクリプトフェッチオプションのうち、暗号化ノンスがinitiating
scriptのフェッチオプションの暗号化ノンス、整合性メタデータが空文字列、パーサーメタデータが"not-parser-inserted"、認証モードがinitiating
scriptのフェッチオプションの認証モード、参照ポリシーがinitiating
scriptのフェッチオプションの参照ポリシー、フェッチ優先度が"auto"のスクリプトフェッチオプションに設定します。
base URLをinitiating scriptのベースURLに設定します。
これらの手順の効果により、setTimeout()およびsetInterval()によって実行される文字列のコンパイルは、eval()によって実行されるものと同様に動作します。つまり、モジュールスクリプトがimport()経由でフェッチされる場合、両方のコンテキストで同じように動作します。
scriptを、handler、settings object、base URL、およびfetch optionsを使用してクラシックスクリプトを作成した結果とします。
クラシックスクリプトを実行します。
もしidがglobalのsetTimeoutとsetInterval IDのマップに存在しない場合、これらの手順を中止します。
もしglobalのsetTimeoutとsetInterval IDのマップ[id]がuniqueHandleと等しくない場合、これらの手順を中止します。
IDは、handler内の著者コードによってclearTimeout()やclearInterval()を呼び出して削除され、その後のsetTimeout()やsetInterval()呼び出しによって再利用された可能性があります。
もしrepeatがtrueの場合、global、handler、timeout、arguments、true、およびidを指定して、再度タイマー初期化手順を実行します。
それ以外の場合、globalのsetTimeoutとsetInterval IDのマップ[id]を削除します。
nesting levelを1増やします。
taskのタイマーネスティングレベルをnesting levelに設定します。
completionStepを、globalにtaskを実行するグローバルタスクをキューに追加するアルゴリズムステップとします。
uniqueHandleをglobal、"setTimeout/setInterval"、timeout、completionStepを指定してタイムアウト後の手順を実行した結果に設定します。
設定する globalのsetTimeoutとsetInterval IDのマップ[id]をuniqueHandleにします。
idを返します。
Web IDLによって定義された引数変換(たとえば、オブジェクトのtoString()メソッドの呼び出しなど)は、このアルゴリズムが実行される前に、Web
IDLで定義されたアルゴリズム内で発生します。
例えば、次のようなコードはログに "ONE TWO " が含まれる結果になります:
var log = '' ;
function logger( s) { log += s + ' ' ; }
setTimeout({ toString: function () {
setTimeout( "logger('ONE')" , 100 );
return "logger('TWO')" ;
} }, 100 );
数ミリ秒間のタスクを遅延なしで連続して実行しつつ、ユーザーインターフェイスをブロックしないようにブラウザに制御を戻すために(また、CPUを占有しすぎてスクリプトが強制終了されないようにするために)、作業を行う前に次のタイマーをキューに入れるだけです:
function doExpensiveWork() {
var done = false ;
// ...
// この関数のこの部分は最大で5ミリ秒かかります
// 完了した場合、done を true に設定します
// ...
return done;
}
function rescheduleWork() {
var id = setTimeout( rescheduleWork, 0 ); // 次回の繰り返しを事前にスケジュールします
if ( doExpensiveWork())
clearTimeout( id); // もう必要なければタイムアウトをクリアします
}
WindowOrWorkerGlobalScope
を実装するオブジェクトには、最初は空の アクティブタイマーのマップ があり、これは 順序付けされたマップ です。
このマップ内の各 キー
は、タイマーを表す ユニークな内部値 であり、各 値 は
タイマーの満了時間を表す DOMHighResTimeStamp
です。
タイムアウト後の手順を実行する には、次の手順を実行します。 WindowOrWorkerGlobalScope
で指定された グローバル、文字列 順序識別子、数値 ミリ秒、および 完了手順 のセットが指定されます。これらの手順は ユニークな内部値 を返します。
timerKey を新しい ユニークな内部値 に設定します。
global に与えられた 現在の高解像度時間 を startTime に設定します。
設定 します。 global の アクティブタイマーのマップ[timerKey] に startTime + milliseconds を設定します。
次のステップを 並行して 実行します:
もし global が Window オブジェクトであれば、
global の 関連付けられた
Document が
完全にアクティブ になり、さらに milliseconds
ミリ秒経過するまで待機します(必ずしも連続的ではありません)。
それ以外の場合、global が WorkerGlobalScope
オブジェクトであれば、
milliseconds ミリ秒が経過するまで、ワーカーが中断されていない状態で待機します(必ずしも連続的ではありません)。
このアルゴリズムの同じ global と orderingIdentifier を持ち、このアルゴリズムの開始前に開始され、その milliseconds がこのアルゴリズムのものと等しいかそれ以下である すべての呼び出しが完了するまで待機します。
オプションとして、さらに 実装依存 の時間だけ待機します。
これは、デバイスの電力使用量を最適化するためにタイムアウトを調整できるようにするためです。例えば、いくつかのプロセッサには低消費電力モードがあり、 そのモードではタイマーの精度が低下します。そのようなプラットフォームでは、ユーザーエージェントはタイマーをこのスケジュールに合わせて遅くすることで、 より正確なモードの使用に伴う高い電力消費を避けることができます。
completionSteps を実行します。
削除 します。global の アクティブタイマーのマップ[timerKey] を削除します。
timerKey を返します。
タイムアウト後の手順を実行する は、
開発者が指定したタイムアウト後に開発者が指定したコードを実行するために、他の仕様書で使用されることを目的としています。
これは setTimeout() に似た方法で行われます。
ただし、setTimeout() のネストやクランプの動作は含まれません。
このような仕様書は、自分の仕様書内のタイムアウトの順序を保証するために orderingIdentifier を選択することができますが、
他の仕様書のタイムアウトに関して順序を制約することはありません。
すべての現行エンジンでサポートされています。
queueMicrotask(callback) メソッドは
マイクロタスクをキューに入れ、
コールバック関数を
« » と "report" と共に callback を呼び出す必要があります。
queueMicrotask()
メソッドは、著者が
マイクロタスクキュー に
コールバックをスケジュールできるようにします。
これにより、コードが次に
JavaScript実行コンテキストスタック が
空になった際に実行されるようになります。
これは、すべての現在実行中の同期JavaScriptが完了するまでの間に発生します。これは、例えばsetTimeout(f, 0)
を使用した場合のように、コントロールが
イベントループ に戻ることはありません。
著者は、多くのマイクロタスクをスケジュールすることが、多くの同期コードを実行するのと同じパフォーマンス上のデメリットを持つことに注意する必要があります。どちらも、ブラウザが描画などの自身の作業を行うことを妨げます。多くのケースでは、requestAnimationFrame()
または
requestIdleCallback()
を使用する方が良い選択肢です。特に、次のレンダリングサイクルの前にコードを実行することが目的である場合、それがrequestAnimationFrame()
の目的です。
以下の例からも分かるように、queueMicrotask()
を最もよく理解する方法は、同期コードを再配置するメカニズムとして考えることです。これにより、キューに入れられたコードが現在実行中の同期JavaScriptが完了した直後に実行されることが効果的に保証されます。
queueMicrotask()
を使用する最も一般的な理由は、情報が同期的に利用可能な場合でも、過度な遅延を導入せずに一貫した順序を作成することです。
例えば、以前にロードされたデータの内部キャッシュを保持するカスタム要素がloadイベントを発火させる場合、次のような単純な実装が考えられます:
MyElement. prototype. loadData = function ( url) {
if ( this . _cache[ url]) {
this . _setData( this . _cache[ url]);
this . dispatchEvent( new Event( "load" ));
} else {
fetch( url). then( res => res. arrayBuffer()). then( data => {
this . _cache[ url] = data;
this . _setData( data);
this . dispatchEvent( new Event( "load" ));
});
}
しかし、この単純な実装には問題があります。それは、ユーザーが一貫しない動作を経験する可能性があるためです。例えば、次のようなコードは
element. addEventListener( "load" , () => console. log( "loaded" ));
console. log( "1" );
element. loadData();
console. log( "2" );
データを取得する必要がある場合は「1, 2, loaded」とログに記録され、データがすでにキャッシュされている場合は「1, loaded,
2」と記録される場合があります。同様に、loadData()の呼び出し後に、要素にデータが設定されているかどうかは一貫しません。
一貫した順序を得るために、queueMicrotask()
を使用できます:
MyElement. prototype. loadData = function ( url) {
if ( this . _cache[ url]) {
queueMicrotask(() => {
this . _setData( this . _cache[ url]);
this . dispatchEvent( new Event( "load" ));
});
} else {
fetch( url). then( res => res. arrayBuffer()). then( data => {
this . _cache[ url] = data;
this . _setData( data);
this . dispatchEvent( new Event( "load" ));
});
}
このように、キューに入れられたコードを JavaScript実行コンテキストスタックが空になった後に実行されるように効果的に再配置することで、要素の状態の一貫した順序と更新を保証します。
別の興味深いqueueMicrotask()
の使用例として、複数の呼び出し元による作業の非協調的な「バッチ処理」を可能にすることが挙げられます。例えば、データをできるだけ早く送信したいライブラリ関数を考えてみますが、容易に回避可能である場合には複数のネットワークリクエストを行いたくない場合。このようなバランスを取る一つの方法は次のようになります:
const queuedToSend = [];
function sendData( data) {
queuedToSend. push( data);
if ( queuedToSend. length === 1 ) {
queueMicrotask(() => {
const stringToSend = JSON. stringify( queuedToSend);
queuedToSend. length = 0 ;
fetch( "/endpoint" , stringToSend);
});
}
このアーキテクチャでは、現在実行中の同期JavaScript内のsendData()への複数の後続の呼び出しが、1つのfetch()
呼び出しにバッチ処理されますが、(setTimeout()を使用した場合のように)フェッチの前にイベントループタスクが介入することはありません。
window.alert(message)
すべての現在のエンジンでサポートされています。
指定されたメッセージを表示するモーダルアラートを表示し、ユーザーがそれを閉じるまで待機します。
result = window.confirm(message)
すべての現在のエンジンでサポートされています。
指定されたメッセージを表示するモーダルOK/キャンセルプロンプトを表示し、ユーザーがそれを閉じるまで待機します。そして、ユーザーがOKをクリックした場合はtrueを、キャンセルをクリックした場合はfalseを返します。
result = window.prompt(message [, default])
すべての現在のエンジンでサポートされています。
指定されたメッセージを表示するモーダルテキストコントロールプロンプトを表示し、ユーザーがそれを閉じるまで待機します。ユーザーがプロンプトをキャンセルした場合はnullを返し、そうでない場合はユーザーが入力した値を返します。第2引数が指定されている場合、その値がデフォルト値として使用されます。
タスク または マイクロタスク に依存するロジック、たとえば メディア要素 がその メディアデータ を読み込んでいるときに、これらのメソッドが呼び出されると停止します。
alert()およびalert(message)メソッドのステップは次のとおりです:
シンプルダイアログを表示できない場合、このメソッドは何もせずに戻ります。
このメソッドが引数なしで呼び出された場合、messageは空の文字列とします。それ以外の場合、messageはメソッドの最初の引数とします。
messageを改行を正規化することにより設定します。
messageをシンプルダイアログの文字列をオプションで切り詰めることにより設定します。
messageをユーザーに表示し、U+000A LFを改行として扱います。
WebDriver
BiDiユーザープロンプトが開かれましたをalertおよびmessageとともに呼び出します。
ユーザーがメッセージを認識するのを待つ間、一時停止をオプションで行います。
WebDriver BiDiユーザープロンプトが閉じましたを呼び出し、trueを返します。
このメソッドは、歴史的な理由でオーバーロードを使用して定義されており、オプションの引数を使用していません。そのため、実際の影響としては、alert(undefined)はalert("undefined")として扱われますが、alert()はalert("")として扱われます。
confirm(message)メソッドのステップは次のとおりです:
シンプルダイアログを表示できない場合、このメソッドはfalseを返して終了します。
messageを改行を正規化することにより設定します。
messageをシンプルダイアログの文字列をオプションで切り詰めることにより設定します。
messageをユーザーに表示し、U+000A LFを改行として扱い、ユーザーに肯定または否定の応答を求めます。
WebDriver
BiDiユーザープロンプトが開かれましたをconfirmおよびmessageとともに呼び出します。
ユーザーが肯定または否定の応答をするまで、一時停止を行います。
WebDriver BiDiユーザープロンプトが閉じましたを呼び出し、ユーザーが肯定的に応答した場合はtrueを、否定的に応答した場合はfalseを返します。
prompt(message, default)メソッドのステップは次のとおりです:
シンプルダイアログを表示できない場合、このメソッドはnullを返して終了します。
messageを改行を正規化することにより設定します。
messageをシンプルダイアログの文字列をオプションで切り詰めることにより設定します。
defaultをシンプルダイアログの文字列をオプションで切り詰めることにより設定します。
messageをユーザーに表示し、U+000A LFを改行として扱い、ユーザーに文字列を入力するか、操作を中止するように求めます。この応答は、defaultで指定された値にデフォルト設定されます。
WebDriver
BiDiユーザープロンプトが開かれましたをprompt、message、およびdefaultとともに呼び出します。
ユーザーの応答を待つ間、一時停止を行います。
ユーザーが操作を中止した場合はresultをnullとし、そうでない場合はユーザーが応答した文字列をresultとします。
WebDriver BiDiユーザープロンプトが閉じましたを呼び出し、resultがnullの場合はfalseを、それ以外の場合はtrueを返します。
resultを返します。
シンプルダイアログの文字列をオプションで切り詰めるためには、s自体、またはsから派生した短い文字列を返します。ユーザーエージェントは、sの省略された部分を表示するためのUIを提供すべきではありません。これは、ユーザーを騙して「重要なセキュリティ警告!全文を表示するには「もっと見る」をクリックしてください!」のようなダイアログを作成するのが簡単になりすぎるためです。
たとえば、ユーザーエージェントはメッセージの最初の100文字だけを表示するようにすることができます。また、文字列の中央を「…」に置き換えることもできます。このような変更は、不自然に大きく、信頼性が高そうなシステムダイアログの濫用可能性を制限するのに役立ちます。
次のアルゴリズムがtrueを返す場合、Window windowに対してシンプルダイアログを表示することができません:
windowの関連するDocumentのアクティブなサンドボックスフラグセットにサンドボックス化されたモーダルフラグが設定されている場合はtrueを返します。
windowの関連する設定オブジェクトの起源とwindowのトップレベル起源が同一起源ドメインでない場合はtrueを返します。
windowの関連するエージェントのイベントループの終了ネスティングレベルがゼロでない場合は、オプションでtrueを返します。
オプションでtrueを返します。(たとえば、ユーザーエージェントがユーザーにすべてのモーダルダイアログを無視するオプションを提供する場合、このメソッドが呼び出されたときに、このステップで終了することができます。)
falseを返します。
すべての最新エンジンでサポートされています。
window.print()
ページを印刷するようにユーザーに促します。
print()メソッドのステップは次のとおりです:
documentをこの要素の関連付けられたDocumentとします。
documentが完全にアクティブでない場合、何もせずに戻ります。
documentのアンロードカウンターが0より大きい場合、何もせずに戻ります。
documentがポストロードタスクの準備ができている場合、documentの印刷手順を実行します。
それ以外の場合、documentのロード時に印刷フラグを設定します。
ユーザーエージェントは、ユーザーが物理的な形を取得する(例: 印刷されたコピー)または物理的な形の表現(例: PDFコピー)をドキュメントから取得する機会を求めるときにも、印刷手順を実行する必要があります。
Document documentに対する印刷手順は次のとおりです:
ユーザーエージェントは、ユーザーにメッセージを表示するか、何もせずに戻る(またはその両方)ことがあります。
たとえば、キオスクブラウザは、print()メソッドの呼び出しを黙って無視することができます。
たとえば、モバイルデバイス上のブラウザは、近くにプリンターがないことを検出し、続行する前に「PDFに保存」オプションを提供するメッセージを表示することができます。
documentのアクティブなサンドボックスフラグセットにサンドボックス化されたモーダルフラグが設定されている場合、何もせずに戻ります。
印刷ダイアログがDocumentのサンドボックスによってブロックされている場合、beforeprintおよびafterprintイベントは発生しません。
ユーザーエージェントは、イベントを発生させる必要があります。documentの関連するグローバルオブジェクトおよびその中の任意の子ナビゲーブルに対してbeforeprintという名前のイベントを発生させます。
ここで子にのみ発生させるのは適切ではなく、いくつかのタスクはキューに入れる必要があるかもしれません。詳細はissue #5096を参照してください。
beforeprintイベントは、たとえばドキュメントが印刷された時刻を追加するなど、印刷されたコピーに注釈を付けるために使用できます。
ユーザーエージェントは、documentの物理的な形を取得する(またはその表現を取得する)機会をユーザーに提供する必要があります。ユーザーエージェントは、ユーザーが受け入れるか拒否するまで待機してから戻ることができます。その場合、ユーザーエージェントはメソッドが待機している間に一時停止を行う必要があります。この時点でユーザーエージェントが待機しない場合でも、最終的に代替形式を作成する際には、このアルゴリズムのこの時点で関連するドキュメントの状態を使用する必要があります。
ユーザーエージェントは、イベントを発生させる必要があります。documentの関連するグローバルオブジェクトおよびその中の任意の子ナビゲーブルに対してafterprintという名前のイベントを発生させます。
ここで子にのみ発生させるのは適切ではなく、いくつかのタスクはキューに入れる必要があるかもしれません。詳細はissue #5096を参照してください。
afterprintイベントは、先のイベントで追加された注釈を元に戻すためや、印刷後のUIを表示するために使用できます。たとえば、ホームローンの申請手順をユーザーに案内しているページの場合、フォームを印刷した後、自動的に次のステップに進むことができます。
Navigator オブジェクトすべての最新エンジンでサポートされています。
Navigator
のインスタンスは、ユーザーエージェント(クライアント)の識別と状態を表します。また、この仕様や他の仕様において、さまざまな API が配置されている一般的なグローバルオブジェクトとしても機能します。
[Exposed =Window ]
interface Navigator {
// このインターフェイスを実装するオブジェクトは、以下のインターフェイスも実装します
};
Navigator includes NavigatorID ;
Navigator includes NavigatorLanguage ;
Navigator includes NavigatorOnLine ;
Navigator includes NavigatorContentUtils ;
Navigator includes NavigatorCookies ;
Navigator includes NavigatorPlugins ;
Navigator includes NavigatorConcurrentHardware ;
これらのインターフェイスミキシンは、WorkerNavigatorがNavigatorインターフェイスの一部を再利用できるように、個別に定義されています。
各Windowには、関連付けられたNavigatorがあり、それはNavigatorオブジェクトです。Windowオブジェクトが作成されると、その関連付けられたNavigatorは、Windowオブジェクトの関連する領域で作成された新しいNavigatorオブジェクトに設定されなければなりません。
すべての最新エンジンでサポートされています。
navigatorと
clientInformation
のゲッターステップは、このオブジェクトの関連付けられた
Navigatorを返すことです。
interface mixin NavigatorID {
readonly attribute DOMString appCodeName ; // constant "Mozilla"
readonly attribute DOMString appName ; // constant "Netscape"
readonly attribute DOMString appVersion ;
readonly attribute DOMString platform ;
readonly attribute DOMString product ; // constant "Gecko"
[Exposed =Window ] readonly attribute DOMString productSub ;
readonly attribute DOMString userAgent ;
[Exposed =Window ] readonly attribute DOMString vendor ;
[Exposed =Window ] readonly attribute DOMString vendorSub ; // constant ""
};
場合によっては、業界全体が最善を尽くしても、Webブラウザーにはバグや制限があり、Web作成者はそれらを回避するための対応策を講じる必要があります。
このセクションでは、これらの問題を回避するために、使用されているユーザーエージェントの種類をスクリプトから判断するために使用できる属性のコレクションを定義します。
ユーザーエージェントには、ナビゲーター互換モードがあり、Chrome、Gecko、またはWebKitのいずれかです。
ナビゲーター互換モードは、NavigatorIDミキシンを、既存のWebコンテンツとの互換性が確認されている属性値の組み合わせと、taintEnabled()およびoscpuの有無に制約します。
クライアントの検出は常に現在の既知のバージョンの検出に限定されるべきであり、将来のバージョンや未知のバージョンは常に完全に準拠していると仮定するべきです。
self.navigator.appCodeName
文字列 "Mozilla" を返します。
self.navigator.appName
文字列 "Netscape" を返します。
self.navigator.appVersion
ブラウザーのバージョンを返します。
self.navigator.platform
プラットフォームの名前を返します。
self.navigator.product
文字列 "Gecko" を返します。
window.navigator.productSub
文字列 "20030107" または "20100101" のいずれかを返します。
self.navigator.userAgent
すべての最新エンジンでサポートされています。
すべての最新エンジンでサポートされています。
完全な `User-Agent` ヘッダーを返します。
window.navigator.vendor
空の文字列、"Apple Computer, Inc." または "Google Inc." のいずれかを返します。
window.navigator.vendorSub
空の文字列を返します。
appCodeName
文字列 "Mozilla" を返す必要があります。
appName
文字列 "Netscape" を返す必要があります。
appVersion
以下のように "5.0 (" で始まる適切な文字列を返す必要があります:
trail とは、"Mozilla/" の接頭辞の後に続く デフォルトの
`User-Agent` 値 の部分文字列を指します。
trail を返します。
trail が "5.0 (Windows" で始まる場合は、"5.0 (Windows)" を返します。
それ以外の場合は、最初の U+003B(;)までの trail の接頭辞に U+0029
右括弧を連結して返します。例えば、"5.0 (Macintosh)"、"5.0 (Android 10)"、"5.0 (X11)"
のように返されます。
platform
ブラウザーが実行されているプラットフォームを表す文字列(例:
"MacIntel"、"Win32"、"Linux x86_64"、"Linux armv81")または、プライバシーおよび互換性のために、別のプラットフォームで一般的に返される文字列を返す必要があります。
product
文字列 "Gecko" を返す必要があります。
productSub
次のリストから適切な文字列を返す必要があります:
文字列 "20030107"。
文字列 "20100101"。
userAgent
デフォルトの
`User-Agent` 値 を返す必要があります。
vendor
次のリストから適切な文字列を返す必要があります:
文字列 "Google Inc."。
空の文字列。
文字列 "Apple Computer, Inc."。
vendorSub
空の文字列を返す必要があります。
もし、ナビゲーター互換モード が Gecko の場合、ユーザーエージェントは以下の部分インターフェースもサポートする必要があります:
partial interface mixin NavigatorID {
[Exposed =Window ] boolean taintEnabled (); // constant false
[Exposed =Window ] readonly attribute DOMString oscpu ;
};
taintEnabled() メソッドは false を返す必要があります。
oscpu
属性のゲッターは、空の文字列または、ブラウザーが実行されているプラットフォームを表す文字列(例:
"Windows NT 10.0; Win64; x64"、"Linux x86_64")を返す必要があります。
このAPIに含まれる情報の中で、ユーザーごとに異なる情報は、ユーザーのプロファイル作成に利用される可能性があります。実際、十分な情報が利用可能であれば、ユーザーを一意に特定することも可能です。このため、ユーザーエージェントの実装者は、このAPIに含める情報を可能な限り少なくすることを強く推奨します。
interface mixin NavigatorLanguage {
readonly attribute DOMString language ;
readonly attribute FrozenArray <DOMString > languages ;
};
self.navigator.language
すべての現在のエンジンでサポートされています。
すべての現在のエンジンでサポートされています。
ユーザーが希望する言語を表す言語タグを返します。
self.navigator.languages
すべての現在のエンジンでサポートされています。
すべての現在のエンジンでサポートされています。
ユーザーの希望する言語を表す言語タグの配列を返します。最も希望される言語が最初に来ます。
最も希望される言語は、navigator.language
によって返される言語です。
A languagechange
イベントは、ユーザーエージェントがユーザーの希望する言語に対する理解が変わったときに、
Window または WorkerGlobalScope
オブジェクトで発生します。
language
有効なBCP 47言語タグを返さなければなりません。これは、考えられる言語か、ユーザーの最も希望する 言語を表します。[BCP47]
languages
有効なBCP 47言語タグのフローズン配列を返さなければなりません。これは、1つ以上の考えられる言語か、ユーザーの希望する言語を表し、最も希望する言語が最初に来ます。同じオブジェクトを返す必要がありますが、ユーザーエージェントが異なる値、または異なる順序で返す必要があるまで同じオブジェクトを返します。[BCP47]
ユーザーエージェントがnavigator.languages
属性を持つWindow
または WorkerGlobalScope
オブジェクト global が新しい言語タグのセットを返す必要があるときは、ユーザーエージェントはグローバルタスクをキューに追加し、DOM操作タスクソースでglobalにイベントを発生させ、そのタスクが実行を開始するまで待つ必要があります。languagechange
をglobalで発生させ、実際に新しい値を返す前にそのタスクが開始されるまで待つ必要があります。
ユーザーエージェントが考えられる言語を決定する際には、以下の点を考慮する必要があります。
en-US"という値が推奨されます。すべてのサービスユーザーが同じ値を使用すると、ユーザー同士を区別する可能性が低くなります。
新たなフィンガープリントベクトルを導入しないために、ユーザーエージェントは、この機能で定義されたAPIとHTTP `
Accept-Language`
ヘッダーのリストを同じにする必要があります。
interface mixin NavigatorOnLine {
readonly attribute boolean onLine ;
};
self.navigator.onLine
すべての現行エンジンでサポートされています。
すべての現行エンジンでサポートされています。
ユーザーエージェントが確実にオフライン(ネットワークから切断)されている場合はfalseを返します。 ユーザーエージェントがオンラインである可能性がある場合はtrueを返します。
The onLine
属性は、ユーザーエージェントがリンクをたどったり、スクリプトがリモートページを要求したときにネットワークに接続しない場合(またはそのような試みが失敗すると分かっている場合)にはfalseを返し、そうでない場合はtrueを返さなければなりません。
navigator.onLine
属性の値が、Window または
WorkerGlobalScope
global で true から false に変わるとき、ユーザーエージェントは
globalタスクをキューに追加し、ネットワークタスクソース に与え、
global で offline
という名前のイベントを発火する必要があります。
逆に、navigator.onLine
属性の値が、Window または
WorkerGlobalScope
global で false から true に変わるとき、ユーザーエージェントは
globalタスクをキューに追加し、
ネットワークタスクソース に与え、
global で online
という名前のイベントを発火する必要があります。
この属性は本質的に信頼できません。コンピュータがネットワークに接続されていても、インターネットアクセスがない場合があります。
この例では、ブラウザがオンラインおよびオフラインになるたびにインジケーターが更新されます。
<!DOCTYPE HTML>
< html lang = "en" >
< head >
< title > Online status</ title >
< script >
function updateIndicator() {
document. getElementById( 'indicator' ). textContent = navigator. onLine ? 'online' : 'offline' ;
}
</ script >
</ head >
< body onload = "updateIndicator()" ononline = "updateIndicator()" onoffline = "updateIndicator()" >
< p > The network is: < span id = "indicator" > (state unknown)</ span >
</ body >
</ html >
registerProtocolHandler()
メソッドNavigator/registerProtocolHandler
interface mixin NavigatorContentUtils {
[SecureContext ] undefined registerProtocolHandler (DOMString scheme , USVString url );
[SecureContext ] undefined unregisterProtocolHandler (DOMString scheme , USVString url );
};
window.navigator.registerProtocolHandler(scheme, url)
scheme に url でハンドラーを登録します。例えば、オンライン電話メッセージングサービスが、sms:
スキームのハンドラーとして自らを登録することで、ユーザーがそのようなリンクをクリックした場合に、そのウェブサイトを使用するオプションが提供されるようになります。 [SMS]
url 内の "%s" は、処理するコンテンツの URL を挿入するプレースホルダーとして使用されます。
ユーザーエージェントが登録をブロックした場合(例えば "http" のハンドラーとして登録しようとした場合など)、"SecurityError" DOMException
をスローします。
url に "%s" 文字列が欠けている場合は、"SyntaxError" DOMException
をスローします。
window.navigator.unregisterProtocolHandler(scheme, url)
Navigator/unregisterProtocolHandler
一つのエンジンでのみサポートされています。
指定された引数に基づいてハンドラーを登録解除します。
ユーザーエージェントが登録解除をブロックした場合(例えば無効なスキームの場合など)、"SecurityError" DOMException
をスローします。
url に "%s" 文字列が欠けている場合は、"SyntaxError" DOMException
をスローします。
registerProtocolHandler(scheme,
url) メソッドの手順は次のとおりです:
プロトコルハンドラーパラメーターを正規化 を実行し、 scheme, url, および this の関連する設定オブジェクト で normalizedScheme, normalizedURLString を取得します。
並行して: normalizedScheme および normalizedURLString の プロトコルハンドラーを登録する。
ユーザーエージェントは、説明された制約内で、何でも好きなことができます。たとえば、ユーザーにプロンプトを表示し、サイトをハンドラーのリストに追加する機会を提供するか、ハンドラーをデフォルトにするか、リクエストをキャンセルするかを選択させることができます。また、ユーザーに関連する情報のみを静かに収集することもできます。
ユーザーエージェントは、ユーザーが登録を拒否した場合でも、サイトがハンドラーを登録したかどうかを追跡し、同じリクエストで繰り返しプロンプトが表示されないようにする必要があります。
もし registerProtocolHandler()
オートメーションモード が this の 関連するグローバルオブジェクト の 関連する Document
に設定されている場合、ユーザーエージェントはまずオートメーションコンテキストにいることを確認する必要があります(参照 WebDriver
のセキュリティ考慮事項)。その後、上記の情報伝達とユーザーの同意収集をスキップし、代わりに registerProtocolHandler()
オートメーションモード の値に基づいて次のことを行います:
autoAccept"
ユーザーが登録詳細を確認し、リクエストを受け入れたかのように動作します。
autoReject"
ユーザーが登録詳細を確認し、リクエストを拒否したかのように動作します。
ユーザーエージェントが次の条件で URL inputURL のためにこのハンドラーを使用する場合:
ユーザー名を設定する inputURL と空の文字列に対して。
パスワードを設定する inputURL と空の文字列に対して。
inputURLString を シリアライゼーション で得た結果とします。
encodedURL を UTF-8 パーセントエンコード を inputURLString に対して実行し、コンポーネントパーセントエンコードセット を使用して結果を得ます。
handlerURLString を normalizedURLString とします。
handlerURLString の最初の "%s" を encodedURL で置き換えます。
resultURL を パーシング の結果として handlerURLString で得た結果とします。
もしユーザーが https://example.com/ にアクセスし、次の呼び出しを行った場合:
navigator. registerProtocolHandler( 'web+soup' , 'soup?url=%s' )
そして、後で https://www.example.net/ を訪問して、次のリンクをクリックした場合:
< a href = "web+soup:chicken-kïwi" > Download our Chicken Kïwi soup!</ a >
...その場合、ユーザーエージェントは次の URL に移動する可能性があります:
https://example.com/soup?url=web+soup:chicken-k%C3%AFwi
このサイトは、スープを合成してユーザーに発送するなど、自分がすることを実行します。
これはハンドラーがいつ使用されるかを定義するものではありません。ある程度、ドキュメント間のナビゲーションモデルの処理 がいくつかの関連ケースを定義していますが、一般的にユーザーエージェントは、ネイティブプラグインやヘルパーアプリケーションにスキームを渡すかどうかを検討する際にこの情報を使用する可能性があります。
unregisterProtocolHandler(scheme,
url) メソッドの手順は次のとおりです:
プロトコルハンドラーパラメーターを正規化 を実行し、 scheme, url, および this の関連する設定オブジェクト で normalizedScheme, normalizedURLString を取得します。
並行して: normalizedScheme と normalizedURLString で記述されたハンドラーを登録解除します。
プロトコルハンドラーパラメーターを正規化する には、文字列 scheme, 文字列 url, および 環境設定オブジェクト environment を使用して次の手順を実行します:
scheme を scheme に設定し、ASCII 小文字に変換 します。
もし scheme が セーフリスト化されたスキーム
でないか、"web+" で始まりその後に 1 つ以上の ASCII
小文字のアルファベット が続かない場合は、"SecurityError" DOMException
をスローします。
これにより、scheme にコロン (例: "mailto:") が含まれていると、エラーがスローされます。
以下のスキームが セーフリスト化されたスキーム です:
bitcoin
ftp
ftps
geo
im
irc
ircs
magnet
mailto
matrix
mms
news
nntp
openpgp4fpr
sftp
sip
sms
smsto
ssh
tel
urn
webcal
wtai
xmpp
このリストは変更される可能性があります。追加すべきスキームがある場合は、フィードバックをお寄せください。
もし url に "%s" が含まれていない場合は、"SyntaxError" DOMException
をスローします。
urlRecord を URL のエンコーディングとパーシング の結果として、 url と environment を使用して得た結果とします。
もし urlRecord が失敗した場合は、"SyntaxError" DOMException
をスローします。
これは、%s プレースホルダーが URL のホストまたはポートに含まれている場合に強制的に適用されます。
もし urlRecord の スキーム が HTTP(S) スキーム でなく、または urlRecord の オリジン が environment の オリジン と 同一オリジン でない場合、"SecurityError" DOMException
をスローします。
アサート: urlRecord が 潜在的に信頼できる URL かどうか を調べた結果として
"潜在的に信頼できる" であること。
プロトコルハンドラーパラメーターを正規化する が 安全なコンテキスト 内で実行されるため、これは 同一オリジン 条件によって暗示されます。
(scheme, urlRecord) を返します。
urlRecord の シリアライゼーション は
有効な URL 文字列 ではありません。なぜなら、 "%s" という文字列が含まれているためです。
カスタムスキームハンドラーは、特にプライバシーに関する懸念を引き起こす可能性があります。
ウェブ全体の利用のハイジャック。 ユーザーエージェントは、その通常の操作に重要なスキーム(HTTP(S) スキーム など)を第三者のサイトを介して再ルーティングすることを許可すべきではありません。これにより、ユーザーの活動が簡単に追跡され、セキュアな接続内でもユーザー情報が収集される可能性があります。
デフォルト設定のハイジャック。 ユーザーエージェントは、デフォルト設定を自動的に変更しないよう強く推奨されます。これは、ユーザーが予期しないリモートホストにデータを送信することにつながる可能性があります。新しいハンドラーが自身を登録しても、それによりそのサイトが自動的に使用されるべきではありません。
登録スパム。
ユーザーエージェントは、サイトが大量のハンドラーを、場合によっては複数のドメインから登録しようとする可能性を考慮すべきです(例えば、異なるドメイン上の一連のページを経由してリダイレクトし、それぞれが
web+spam:
のようなスキームのハンドラーを登録するなど。ポルノサイトが長年にわたり他のウェブブラウザ機能を悪用してきた類似の手法があります)。ユーザーエージェントは、そのような敵対的な試みを優雅に処理し、ユーザーを保護するべきです。
悪意のあるハンドラーメタデータ。 ユーザーエージェントは、インターフェイスに埋め込まれた文字列に対する典型的な攻撃に対して保護する必要があります。例えば、そのような文字列内のマークアップやエスケープ文字が実行されないようにすること、ヌルバイトが適切に処理されること、長すぎる文字列がクラッシュやバッファオーバーランを引き起こさないようにすることなどが必要です。
プライベートデータの漏洩。 ウェブページの作者は、プライベートと見なされるURLデータを使用してカスタムスキームハンドラーを参照する場合があります。彼らは、ユーザーの選択したハンドラーが組織内のページを指しており、機密データが第三者に漏れないことを期待しているかもしれません。しかし、ユーザーが外部サイトを指すハンドラーを登録している場合、そのデータが第三者に漏洩する可能性があります。実装者は、特定のサブドメイン、コンテンツタイプ、またはスキームでカスタムハンドラーを無効にするオプションを提供することを検討するかもしれません。
インターフェイス干渉。 ユーザーエージェントは、メソッドへの非常に長い引数に対処できるように準備すべきです。例えば、表示されるユーザーインターフェースが「受け入れる」ボタンと「拒否する」ボタンで構成され、「受け入れる」ボタンがハンドラーの名前を含んでいる場合、長い名前が「拒否する」ボタンを画面外に押し出さないようにすることが重要です。
各Documentには、registerProtocolHandler() 自動化モードがあり、デフォルトは
"none"
ですが、"autoAccept"
または "autoReject"
に設定することも可能です。
ユーザーエージェントの自動化およびウェブサイトのテストの目的で、この標準はRPH登録モードを設定 WebDriver 拡張コマンドを定義します。これは、ユーザーエージェントにDocumentをモードに置き、ユーザーが登録確認プロンプトダイアログを受け入れるか拒否するかを自動的にシミュレートするよう指示します。
| HTTP メソッド | URI テンプレート |
|---|---|
`POST`
| /session/{session id}/custom-handlers/set-mode
|
リモートエンドの手順は以下の通りです:
もしparametersがJSONオブジェクトでない場合、WebDriverエラーをwithWebDriverエラーコード無効な引数と共に返します。
parametersから"mode"という名前のプロパティを取得することで、modeを取得します。
もしmodeが"autoAccept"、"autoReject"、または"none"でない場合、WebDriverエラーをwithWebDriverエラーコード無効な引数と共に返します。
documentを現在のブラウジングコンテキストのアクティブドキュメントとして設定します。
documentのregisterProtocolHandler()自動化モードをmodeに設定します。
成功と共にデータをnullで返します。
interface mixin NavigatorCookies {
readonly attribute boolean cookieEnabled ;
};
window.navigator.cookieEnabled
すべての現在のエンジンでサポートされています。
クッキーの設定が無視される場合は false を返し、それ以外の場合は true を返します。
cookieEnabled 属性は、ユーザーエージェントが HTTP State Management
Mechanism に従ってクッキーを処理しようとする場合に true を返し、クッキー変更要求を無視する場合に false を返さなければなりません。[COOKIES]
window.navigator.pdfViewerEnabled
ユーザーエージェントが PDF ファイルを ナビゲートするときにインライン表示をサポートしている場合は true を返し、それ以外の場合は false を返します。後者の場合、PDF ファイルは 外部ソフトウェアで処理されます。
interface mixin NavigatorPlugins {
[SameObject ] readonly attribute PluginArray plugins ;
[SameObject ] readonly attribute MimeTypeArray mimeTypes ;
boolean javaEnabled ();
readonly attribute boolean pdfViewerEnabled ;
};
[Exposed =Window ,
LegacyUnenumerableNamedProperties ]
interface PluginArray {
undefined refresh ();
readonly attribute unsigned long length ;
getter Plugin ? item (unsigned long index );
getter Plugin ? namedItem (DOMString name );
};
[Exposed =Window ,
LegacyUnenumerableNamedProperties ]
interface MimeTypeArray {
readonly attribute unsigned long length ;
getter MimeType ? item (unsigned long index );
getter MimeType ? namedItem (DOMString name );
};
[Exposed =Window ,
LegacyUnenumerableNamedProperties ]
interface Plugin {
readonly attribute DOMString name ;
readonly attribute DOMString description ;
readonly attribute DOMString filename ;
readonly attribute unsigned long length ;
getter MimeType ? item (unsigned long index );
getter MimeType ? namedItem (DOMString name );
};
[Exposed =Window ]
interface MimeType {
readonly attribute DOMString type ;
readonly attribute DOMString description ;
readonly attribute DOMString suffixes ;
readonly attribute Plugin enabledPlugin ;
};
現在では、PDF ビューアーのサポートを検出するには navigator.pdfViewerEnabled
を使用することができますが、歴史的な理由から、同じ機能を提供する複雑かつ相互に関連するインターフェースがいくつか存在しており、レガシーコードはそれに依存しています。このセクションでは、シンプルな現代的バリアントと複雑な歴史的バリアントの両方を指定します。
各ユーザーエージェントには、PDF ビューアー対応ブール値があり、その値は 実装依存です(ユーザーの設定によって変わる可能性があります)。
この値は、ナビゲーション処理モデルにも影響を与えます。
各 Window オブジェクトには、PDF ビューアープラグインオブジェクトリストがあります。ユーザー
エージェントの PDF ビューアー対応 が false
の場合、このリストは空です。それ以外の場合は、次の5つの Plugin
オブジェクトを含むリストです。それぞれの 名前 は次の通りです:
PDF Viewer"
Chrome PDF Viewer"
Chromium PDF Viewer"
Microsoft Edge PDF Viewer"
WebKit built-in PDF"
上記のリストの値は PDF ビューアープラグイン名リストを形成します。
これらの名前は、ウェブサイトが歴史的に検索する内容に基づいて選択されたものであり、既存のコンテンツとの互換性を維持するためにユーザーエージェントが公開する必要があるものです。アルファベット順に並べられています。
"PDF Viewer" の名前は、汎用プラグイン名を指すように enabledPlugin
のゲッターに対応させるために、0 番目の位置に挿入されました。
各 Window オブジェクトには、PDF ビューアー MIME タイプオブジェクトリストがあります。ユーザー
エージェントの PDF ビューアー対応 が false
の場合、このリストは空です。それ以外の場合は、次の2つの MimeType
オブジェクトを含むリストです。それぞれの 種類 は次の通りです:
application/pdf"
text/pdf"
上記のリストの値は PDF ビューアー MIME タイプリストを形成します。
各 NavigatorPlugins
オブジェクトには、プラグイン配列があり、これは新しい PluginArray であり、また新しい MIME タイプ配列があり、これは新しい MimeTypeArray です。
NavigatorPlugins ミックスインの
plugins
ゲッターステップは、このオブジェクトの プラグイン配列を返すことです。
NavigatorPlugins ミックスインの
mimeTypes ゲッターステップは、このオブジェクトの MIME タイプ配列を返すことです。
NavigatorPlugins ミックスインの
javaEnabled() メソッドステップは、false を返すことです。
すべての現行エンジンでサポートされています。
NavigatorPlugins ミックスインの
pdfViewerEnabled ゲッターステップは、ユーザーエージェントの PDF ビューアー対応 を返すことです。
PluginArray インターフェースは 名前付きプロパティをサポート
します。ユーザーエージェントの PDF ビューアー対応 が
true の場合、それらは PDF
ビューアープラグイン名 です。それ以外の場合、それらは空のリストです。
PluginArray インターフェースの namedItem(name) メソッドステップは次の通りです:
各 Plugin プラグイン に対して、このオブジェクトの 関連グローバルオブジェクト の PDF
ビューアープラグインオブジェクト の中から、もし プラグイン の 名前 が name である場合、それを返します。
null を返します。
PluginArray インターフェースは インデックス付きプロパティをサポート します。サポートされているプロパティのインデックス は、インデックス です。このオブジェクトの
関連グローバルオブジェクト の PDF ビューアープラグインオブジェクト
です。
PluginArray インターフェースの item(index) メソッドステップは次の通りです:
plugins を このオブジェクトの 関連グローバルオブジェクト の PDF ビューアープラグインオブジェクト に設定します。
もし index が plugins の サイズ より小さい場合、それを返します。
null を返します。
PluginArray インターフェースの length
ゲッターステップは、このオブジェクトの 関連グローバルオブジェクト の PDF ビューアープラグインオブジェクト の サイズ を返すことです。
PluginArray インターフェースの refresh()
メソッドステップは、何も行わないことです。
MimeTypeArray インターフェースは 名前付きプロパティをサポート します。ユーザーエージェントの PDF ビューアー対応 が true の場合、それらは PDF ビューアー MIME タイプ です。それ以外の場合、それらは空のリストです。
MimeTypeArray インターフェースの namedItem(name) メソッドステップは次の通りです:
各 MimeType mimeType に対して、このオブジェクトの 関連グローバルオブジェクト の PDF ビューアー
MIME タイプオブジェクト の中から、もし mimeType の 種類 が name である場合、それを返します。
null を返します。
MimeTypeArray インターフェースは インデックス付きプロパティをサポート します。サポートされているプロパティのインデックス は、インデックス です。このオブジェクトの
関連グローバルオブジェクト の PDF ビューアー MIME
タイプオブジェクト です。
MimeTypeArray インターフェースの item(index) メソッドステップは次の通りです:
mimeTypes を このオブジェクトの 関連グローバルオブジェクト の PDF ビューアー MIME タイプオブジェクト に設定します。
もし index が mimeTypes の サイズ より小さい場合、それを返します。
null を返します。
MimeTypeArray インターフェースの length
ゲッターステップは、このオブジェクトの 関連グローバルオブジェクト の PDF ビューアー MIME タイプオブジェクト の サイズ を返すことです。
各 Plugin オブジェクトには、名前 があり、オブジェクトの作成時に設定されます。
Plugin インターフェースの name ゲッターステップは、このオブジェクトの
名前 を返すことです。
Plugin インターフェースの description
ゲッターステップは、「Portable Document Format」を返すことです。
Plugin インターフェースの filename
ゲッターステップは、「internal-pdf-viewer」を返すことです。
Plugin インターフェースは 名前付きプロパティをサポート します。ユーザーエージェントの PDF ビューアー対応 が true の場合、それらは PDF ビューアー MIME タイプ です。それ以外の場合、それらは空のリストです。
Plugin インターフェースの namedItem(name) メソッドステップは次の通りです:
各 MimeType mimeType に対して、このオブジェクトの 関連グローバルオブジェクト の PDF ビューアー
MIME タイプオブジェクト の中から、もし mimeType の 種類 が name である場合、それを返します。
null を返します。
Plugin インターフェースは インデックス付きプロパティをサポート します。サポートされているプロパティのインデックス は、インデックス です。このオブジェクトの
関連グローバルオブジェクト の PDF ビューアー MIME
タイプオブジェクト です。
Plugin インターフェースの item(index)
メソッドステップは次の通りです:
mimeTypes を このオブジェクトの 関連グローバルオブジェクト の PDF ビューアー MIME タイプオブジェクト に設定します。
もし index が mimeType の サイズ より小さい場合、それを返します。
null を返します。
Plugin インターフェースの length ゲッターステップは、このオブジェクトの
関連グローバルオブジェクト の PDF ビューアー MIME
タイプオブジェクト の サイズ を返すことです。
各 MimeType オブジェクトには 種類 があり、オブジェクトの作成時に設定されます。
MimeType インターフェースの type ゲッターステップは、このオブジェクトの
種類 を返すことです。
MimeType インターフェースの description
ゲッターステップは、「Portable Document Format」を返すことです。
MimeType インターフェースの suffixes
ゲッターステップは、「pdf」を返すことです。
MimeType インターフェースの enabledPlugin
ゲッターステップは、このオブジェクトの 関連グローバルオブジェクト の PDF ビューアープラグインオブジェクト[0]
(つまり、汎用の「PDF Viewer」プラグイン) を返すことです。
すべての現在のエンジンでサポートされています。
[Exposed =(Window ,Worker ), Serializable , Transferable ]
interface ImageBitmap {
readonly attribute unsigned long width ;
readonly attribute unsigned long height ;
undefined close ();
};
typedef (CanvasImageSource or
Blob or
ImageData ) ImageBitmapSource ;
enum ImageOrientation { " from-image " , " flipY " };
enum PremultiplyAlpha { " none " , " premultiply " , " default " };
enum ColorSpaceConversion { " none " , " default " };
enum ResizeQuality { " pixelated " , " low " , " medium " , " high " };
dictionary ImageBitmapOptions {
ImageOrientation imageOrientation = "from-image";
PremultiplyAlpha premultiplyAlpha = "default";
ColorSpaceConversion colorSpaceConversion = "default";
[EnforceRange ] unsigned long resizeWidth ;
[EnforceRange ] unsigned long resizeHeight ;
ResizeQuality resizeQuality = "low";
};
ImageBitmap
オブジェクトは、キャンバスに描画できるビットマップ画像を表し、過度な遅延なしに使用できます。
過度な遅延の判断は実装者に委ねられていますが、一般的にビットマップの使用にネットワークI/OやローカルディスクI/Oが必要な場合、その遅延は過度と見なされる可能性があります。一方、GPUまたはシステムRAMからのブロッキングリードのみが必要な場合、その遅延は許容範囲と見なされる可能性があります。
promise = self.createImageBitmap(image [, options ])
すべての現在のエンジンでサポートされています。
promise = self.createImageBitmap(image, sx, sy, sw, sh [, options ])
imageは、img要素、SVG image要素、video要素、canvas要素、Blobオブジェクト、ImageDataオブジェクト、または別のImageBitmapオブジェクトであり、新しいImageBitmapが作成されたときに解決されるPromiseを返します。
たとえば、提供されたimageデータが実際には画像でない場合など、ImageBitmapオブジェクトを作成できない場合、Promiseは拒否されます。
sx、sy、sw、shの引数が提供されている場合、ソース画像は指定されたピクセルにクロップされ、元の画像に存在しないピクセルは透明な黒で置き換えられます。これらの座標は、ソース画像のピクセル座標空間であり、CSSピクセルではありません。
optionsが提供されている場合、ImageBitmapオブジェクトのビットマップデータはoptionsに従って変更されます。たとえば、premultiplyAlphaオプションが"premultiply"に設定されている場合、ビットマップデータのカラーチャネルがアルファチャンネルによって乗算されます。
ソース画像が有効な状態でない場合(例: 正常に読み込まれていない img 要素、[[Detached]] 内部スロット値が true の ImageBitmap オブジェクト、data 属性値の
[[ViewedArrayBuffer]] 内部スロットが切り離されている ImageData オブジェクト、またはビットマップ画像として解釈できないデータを持つ
Blob)、DOMException
の "InvalidStateError" でプロミスを拒否します。
ソース画像の画像データにスクリプトがアクセスできない場合(例: CORS
クロスオリジンの video
や、別のオリジンからのワーカーによって描画されている canvas など)、DOMException
の "SecurityError" でプロミスを拒否します。
imageBitmap.close()
すべての現在のエンジンでサポートされています。
imageBitmapの基礎となるビットマップデータを解放します。
imageBitmap.width
すべての現在のエンジンでサポートされています。
imageBitmap.height
すべての現在のエンジンでサポートされています。
ImageBitmap オブジェクトの[[Detached]]内部スロット値がfalseである場合、常に幅と高さを持つ関連するビットマップデータがあります。ただし、このデータが破損している可能性もあります。ImageBitmapオブジェクトのメディアデータがエラーなしにデコードできる場合、そのオブジェクトは完全にデコード可能であると言います。
ImageBitmapオブジェクトのビットマップにはorigin-cleanフラグがあり、これはビットマップが異なるオリジンからのコンテンツによって汚染されているかどうかを示します。このフラグは初期状態でtrueに設定されており、createImageBitmap()のステップによってfalseに変更されることがあります。
ImageBitmapオブジェクトはシリアライズ可能なオブジェクトであり、転送可能なオブジェクトです。
彼らのシリアライズステップは、valueとserializedを受け取る際に次のようになります。
valueのorigin-cleanフラグが設定されていない場合、"DataCloneError"DOMExceptionをスローします。
serialized.[[BitmapData]]にvalueのビットマップデータのコピーを設定します。
彼らのデシリアライズステップは、serialized、value、およびtargetRealmを受け取る際に次のようになります。
valueのビットマップデータをserialized.[[BitmapData]]に設定します。
彼らの転送ステップは、valueとdataHolderを受け取る際に次のようになります。
valueのorigin-cleanフラグが設定されていない場合、"DataCloneError"DOMExceptionをスローします。
dataHolder.[[BitmapData]]にvalueのビットマップデータを設定します。
valueのビットマップデータを未設定にします。
彼らの転送受信ステップは、dataHolderとvalueを受け取る際に次のようになります。
valueのビットマップデータをdataHolder.[[BitmapData]]に設定します。
createImageBitmap(image, options)およびcreateImageBitmap(image, sx, sy, sw, sh, options)メソッドが呼び出されたとき、次のステップを実行する必要があります。
sw または sh のいずれかが指定されており、その値が 0 の場合、RangeError
で 拒否されたプロミス を返します。
optionsのresizeWidthまたはoptionsのresizeHeightが存在し、0である場合、拒否されたPromiseを"InvalidStateError" DOMExceptionを返します。
画像引数の使用可能性を確認します。これが例外をスローするか、悪いを返す場合、拒否されたPromiseを"InvalidStateError" DOMExceptionを返します。
pを新しいPromiseに設定します。
imageBitmapを新しいImageBitmapオブジェクトに設定します。
imageに基づいてスイッチします。
img
image
imageのメディアデータに自然な寸法がない場合(例えば、指定されたコンテンツサイズのないベクターグラフィックである場合)およびoptionsのresizeWidthまたはoptionsのresizeHeightが存在しない場合、拒否されたPromiseを"InvalidStateError"DOMExceptionを返します。
imageのメディアデータに自然な寸法がない場合(例えば、指定されたコンテンツサイズのないベクターグラフィックである場合)、それはresizeWidthおよびresizeHeightオプションによって指定されたサイズにレンダリングされる必要があります。
imageBitmapのビットマップデータをimageのメディアデータのコピーに設定し、ソース矩形にフォーマット付きでトリミングされたものにします。これがアニメーション画像である場合、imageBitmapのビットマップデータは、アニメーションがサポートされていないか無効にされているときに使用されるとフォーマットで定義されているデフォルト画像からのみ取得される必要があり、そうでない場合はアニメーションの最初のフレームから取得される必要があります。
imageがorigin-cleanではない場合、imageBitmapのビットマップのorigin-cleanフラグをfalseに設定します。
このステップを並列で実行します。
pをimageBitmapで解決します。
video
imageのnetworkState属性がNETWORK_EMPTYである場合、拒否されたPromiseを"InvalidStateError"DOMExceptionを返します。
imageBitmapのビットマップデータを、現在の再生位置のフレームのコピーに設定し、メディアリソースの自然な幅と自然な高さで(つまり、アスペクト比の補正が適用された後に)、ソース矩形にフォーマット付きでトリミングされたものにします。
imageがorigin-cleanではない場合、imageBitmapのビットマップのorigin-cleanフラグをfalseに設定します。
このステップを並列で実行します。
pをimageBitmapで解決します。
canvas
imageBitmapのビットマップデータを、imageのビットマップデータのコピーに設定し、ソース矩形にフォーマット付きでトリミングされたものにします。
imageBitmapのビットマップのorigin-cleanフラグを、imageのビットマップのorigin-cleanフラグと同じ値に設定します。
このステップを並列で実行します。
pをimageBitmapで解決します。
Blob
これらのステップを並列で実行します。
imageDataをimageのデータを読み取った結果に設定します。オブジェクトの読み取り中にエラーが発生した場合、pを"InvalidStateError"DOMExceptionで拒否し、これらのステップを中止します。
画像のスニッフィングルールを適用して、imageDataのファイル形式を決定します。imageのMIMEタイプ(imageのtype属性で示される)を公式のタイプとして使用します。
imageDataがサポートされている画像ファイル形式でない場合(例えば、全く画像でない場合)、またはimageDataが致命的な方法で破損しており、画像の寸法を取得できない場合(例えば、自然なサイズのないベクターグラフィックの場合)、pを"InvalidStateError"DOMExceptionで拒否し、これらのステップを中止します。
imageBitmapのビットマップデータをimageDataに設定し、ソース矩形にフォーマット付きでトリミングされたものにします。これがアニメーション画像である場合、imageBitmapのビットマップデータは、アニメーションがサポートされていないか無効にされているときに使用されるとフォーマットで定義されているデフォルト画像からのみ取得される必要があり、そうでない場合はアニメーションの最初のフレームから取得される必要があります。
pをimageBitmapで解決します。
ImageData
bufferをimageのdata属性値の[[ViewedArrayBuffer]]内部スロットに設定します。
IsDetachedBuffer(buffer)がtrueの場合、拒否されたPromiseを"InvalidStateError"DOMExceptionで返します。
imageBitmapのビットマップデータをimageの画像データに設定し、ソース矩形にフォーマット付きでトリミングされたものにします。
このステップを並列で実行します。
pをimageBitmapで解決します。
ImageBitmap
imageBitmapのビットマップデータをimageのビットマップデータのコピーに設定し、ソース矩形にフォーマット付きでトリミングされたものにします。
imageBitmapのビットマップのorigin-cleanフラグを、imageのビットマップのorigin-cleanフラグと同じ値に設定します。
このステップを並列で実行します。
pをimageBitmapで解決します。
VideoFrame
imageBitmapのビットマップデータをimageの可視ピクセルデータのコピーに設定し、ソース矩形にフォーマット付きでトリミングされたものにします。
このステップを並列で実行します。
pをimageBitmapで解決します。
pを返します。
上記のステップでユーザーエージェントがビットマップデータをソース矩形にフォーマット付きでトリミングする必要がある場合、ユーザーエージェントは次のステップを実行する必要があります。
inputを変換されているビットマップデータに設定します。
指定された場合はsx、sy、sw、およびshを使用し、sourceRectangleを次の4点(sx、sy)、(sx+sw、sy)、(sx+sw、sy+sh)、(sx、sy+sh)の角を持つ矩形に設定します。それ以外の場合、sourceRectangleを次の4点(0、0)、(inputの幅、0)、(inputの幅、inputの高さ)、(0、inputの高さ)の角を持つ矩形に設定します。
swまたはshのいずれかが負の場合、この矩形の左上の角は、(sx、sy)点の左または上に位置します。
outputWidthを次のように決定します。
resizeWidthオプションメンバーが指定されている場合
resizeWidthメンバーの値
resizeWidthオプションメンバーが指定されていないが、resizeHeightメンバーが指定されている場合
resizeHeightメンバーの値を掛け、sourceRectangleの高さで割った値を、最も近い整数に切り上げたもの
resizeWidthとresizeHeightの両方が指定されていない場合
outputHeightを次のように決定します。
resizeHeightオプションメンバーが指定されている場合
resizeHeightメンバーの値
resizeHeightオプションメンバーが指定されていないが、resizeWidthメンバーが指定されている場合
resizeWidthメンバーの値を掛け、sourceRectangleの幅で割った値を、最も近い整数に切り上げたもの
resizeWidthもresizeHeightも指定されていない場合
inputを無限の透明な黒グリッド面に配置し、その左上の角が面の原点に位置するようにし、x座標が右に向かって増加し、y座標が下に向かって増加し、input画像データの各ピクセルが面のグリッド上のセルを占めるようにします。
outputをsourceRectangleによって示される面上の矩形に設定します。
outputをoutputWidthとoutputHeightで指定されたサイズにスケーリングします。ユーザーエージェントは、スケーリングアルゴリズムの選択をガイドするためにresizeQualityオプションの値を使用する必要があります。
optionsのimageOrientationメンバーの値が"flipY"の場合、outputは、ソースの画像の方向メタデータ(例えば、EXIFメタデータなど)があってもそれを無視して垂直に反転される必要があります。[EXIF]
値が"from-image"の場合、追加のステップは不要です。
以前は"none"という列挙値がありましたが、"from-image"に名前が変更されました。将来的には、"none"が別の意味で追加される予定です。
imageがimg要素またはBlobオブジェクトである場合、valをoptionsのcolorSpaceConversionメンバーの値に設定し、次のサブステップを実行します。
valが"default"の場合、色空間変換の動作は実装依存であり、キャンバスに画像を描画するために使用するデフォルトの色空間に応じて選択されるべきです。
valが"none"の場合、outputは色空間変換を行わずにデコードされる必要があります。これにより、画像デコードアルゴリズムはソースデータに埋め込まれた色プロファイルメタデータや表示デバイスの色プロファイルを無視する必要があります。
valをpremultiplyAlphaメンバーの値に設定し、次のサブステップを実行します。
valが"default"の場合、アルファの前乗算動作は実装依存であり、キャンバスに画像を描画するために最適と考えられるものを選択すべきです。
valが"premultiply"の場合、アルファによって前乗算されていないoutputは、色成分をアルファによって乗算され、アルファによって前乗算されているものはそのままにしておく必要があります。
valが"none"の場合、アルファによって前乗算されていないoutputはそのままにしておき、アルファによって前乗算されているものは、その色成分をアルファで除算する必要があります。
outputを返します。
close()メソッドのステップは次のとおりです。
thisの[[Detached]]内部スロット値をtrueに設定します。
widthゲッターステップは次のとおりです。
thisの[[Detached]]内部スロット値がtrueの場合、0を返します。
heightゲッターステップは次のとおりです。
thisの[[Detached]]内部スロット値がtrueの場合、0を返します。
ResizeQuality列挙型は、画像をスケーリングする際の補間品質の優先度を表現するために使用されます。
"pixelated"の値は、画像のピクセル化を可能な限り保持するようなスケーリングを優先し、ターゲットサイズが元のサイズの整数倍でない場合に画像が歪まないように必要に応じてわずかなスムージングを行うことを示します。
"pixelated"を実装するには、まず各軸ごとに、ターゲットサイズに最も近い整数倍で、元のサイズよりも大きい値を決定します。それをこの整数倍サイズに最近傍補間でスケーリングし、その後、バイリニア補間を使用して残りのサイズにスケーリングします。
"low"の値は、低品質の画像補間品質の優先度を示します。低品質の画像補間は、より高い設定よりも計算コストが低い場合があります。
"medium"の値は、画像補間品質の中程度のレベルを優先することを示します。
"high"の値は、画像補間品質の高いレベルを優先することを示します。高品質の画像補間は、低い設定よりも計算コストが高い場合があります。
バイリニアスケーリングは、比較的高速で低品質の画像スムージングアルゴリズムの一例です。バイキュービックスケーリングやランチョススケーリングは、より高品質な出力を生成する画像スケーリングアルゴリズムの一例です。この仕様では、"pixelated"について上記で説明した特定の補間アルゴリズムの使用を義務付けていません。
このAPIを使用すると、スプライトシートを事前に切り取って準備できます。
var sprites = {};
function loadMySprites() {
var image = new Image();
image. src = 'mysprites.png' ;
var resolver;
var promise = new Promise( function ( arg) { resolver = arg });
image. onload = function () {
resolver( Promise. all([
createImageBitmap( image, 0 , 0 , 40 , 40 ). then( function ( image) { sprites. person = image }),
createImageBitmap( image, 40 , 0 , 40 , 40 ). then( function ( image) { sprites. grass = image }),
createImageBitmap( image, 80 , 0 , 40 , 40 ). then( function ( image) { sprites. tree = image }),
createImageBitmap( image, 0 , 40 , 40 , 40 ). then( function ( image) { sprites. hut = image }),
createImageBitmap( image, 40 , 40 , 40 , 40 ). then( function ( image) { sprites. apple = image }),
createImageBitmap( image, 80 , 40 , 40 , 40 ). then( function ( image) { sprites. snake = image })
]));
};
return promise;
}
function runDemo() {
var canvas = document. querySelector( 'canvas#demo' );
var context = canvas. getContext( '2d' );
context. drawImage( sprites. tree, 30 , 10 );
context. drawImage( sprites. snake, 70 , 10 );
}
loadMySprites(). then( runDemo);
一部のオブジェクトには、AnimationFrameProviderインターフェースミックスインが含まれています。
callback FrameRequestCallback = undefined (DOMHighResTimeStamp time );
interface mixin AnimationFrameProvider {
unsigned long requestAnimationFrame (FrameRequestCallback callback );
undefined cancelAnimationFrame (unsigned long handle );
};
Window includes AnimationFrameProvider ;
DedicatedWorkerGlobalScope includes AnimationFrameProvider ;
各AnimationFrameProviderオブジェクトには、プロバイダの内部状態を保持するターゲットオブジェクトもあります。それは次のように定義されます:
AnimationFrameProviderがWindowである場合
Windowの関連するDocument
AnimationFrameProviderがDedicatedWorkerGlobalScopeである場合
DedicatedWorkerGlobalScope
各ターゲットオブジェクトには、アニメーションフレームコールバックのマップがあり、これは初期状態で空の順序付きマップであり、アニメーションフレームコールバック識別子を持ち、最初はゼロに設定されています。
AnimationFrameProviderのproviderは、以下のいずれかが真である場合、サポートされていると見なされます:
providerがWindowである場合。
providerの所有者セットにあるDedicatedWorkerGlobalScopeオブジェクトがサポートされている場合。
すべての現在のエンジンでサポートされています。
requestAnimationFrame(callback)
メソッドの手順は次のとおりです:
thisがサポートされていない場合は、
"NotSupportedError"をスローし、
DOMExceptionを返します。
targetをthisのターゲットオブジェクトに設定します。
targetのアニメーションフレームコールバック識別子を1増やし、 handleをその結果として設定します。
callbacksをtargetのアニメーションフレームコールバックのマップに設定します。
設定する callbacks[handle] を callbackに。
handleを返します。
すべての現在のエンジンでサポートされています。
cancelAnimationFrame(handle)
メソッドの手順は次のとおりです:
this
がサポートされていない場合は、
"NotSupportedError"をスローし、
DOMExceptionを返します。
callbacksをthisのターゲットオブジェクトのアニメーションフレームコールバックのマップに設定します。
削除する callbacks[handle]。
アニメーションフレームコールバックを実行するために、ターゲットオブジェクト targetとタイムスタンプnowが与えられた場合:
callbacksをtargetのアニメーションフレームコールバックのマップに設定します。
callbackHandlesをキーを取得することによってcallbacksの結果として設定します。
各 handleについて、 もしhandleが存在するならば、 callbacksの中で:
callbackをcallbacks[handle]に設定します。
削除する callbacks[handle]。
コールバック関数を呼び出す
「now」と「report」を渡して。
ワーカー内で、requestAnimationFrame()
は、OffscreenCanvas
と一緒に使用されます。まず、ドキュメント内でワーカーに制御を移します:
const offscreenCanvas = document. getElementById( "c" ). transferControlToOffscreen();
worker. postMessage( offscreenCanvas, [ offscreenCanvas]);
次に、ワーカー内で、以下のコードは左から右に動く四角形を描画します:
let ctx, pos = 0 ;
function draw( dt) {
ctx. clearRect( 0 , 0 , 100 , 100 );
ctx. fillRect( pos, 0 , 10 , 10 );
pos += 10 * dt;
requestAnimationFrame( draw);
}
self. onmessage = function ( ev) {
const transferredCanvas = ev. data;
ctx = transferredCanvas. getContext( "2d" );
draw();
};
WebSocket
インターフェイスはここに定義されていましたが、現在は WebSockets に定義されています。[WEBSOCKETS]
MessageEvent
インターフェイスすべての現在のエンジンでサポートされています。
サーバー送信イベントのメッセージ、
クロスドキュメントメッセージング、
チャネルメッセージング、
ブロードキャストチャネル、
そして WebSockets は、そのMessageEvent
インターフェイスを使用してmessage
イベントを処理します:[WEBSOCKETS]
[Exposed =(Window ,Worker ,AudioWorklet )]
interface MessageEvent : Event {
constructor (DOMString type , optional MessageEventInit eventInitDict = {});
readonly attribute any data ;
readonly attribute USVString origin ;
readonly attribute DOMString lastEventId ;
readonly attribute MessageEventSource ? source ;
readonly attribute FrozenArray <MessagePort > ports ;
undefined initMessageEvent (DOMString type , optional boolean bubbles = false , optional boolean cancelable = false , optional any data = null , optional USVString origin = "", optional DOMString lastEventId = "", optional MessageEventSource ? source = null , optional sequence <MessagePort > ports = []);
};
dictionary MessageEventInit : EventInit {
any data = null ;
USVString origin = "";
DOMString lastEventId = "";
MessageEventSource ? source = null ;
sequence <MessagePort > ports = [];
};
typedef (WindowProxy or MessagePort or ServiceWorker ) MessageEventSource ;
event.data
すべての現在のエンジンでサポートされています。
メッセージのデータを返します。
event.origin
すべての現在のエンジンでサポートされています。
メッセージのオリジンを返します。サーバー送信イベントおよび クロスドキュメントメッセージングの場合。
event.lastEventId
すべての現在のエンジンでサポートされています。
サーバー送信イベントのために、最後のイベントID文字列を返します。
event.source
すべての現在のエンジンでサポートされています。
WindowProxy、クロスドキュメントメッセージング、接続イベントで接続されているMessagePort、およびSharedWorkerGlobalScopeオブジェクトで発生するconnectイベントの source プロパティを返します。
event.ports
すべての現在のエンジンでサポートされています。
クロスドキュメントメッセージングおよびチャネルメッセージングのために、メッセージと一緒に送信されるMessagePort配列を返します。
data
属性は、初期化された値を返さなければなりません。これは送信されるメッセージを表します。
origin
属性は、初期化された値を返さなければなりません。これは、サーバー送信イベントおよびクロスドキュメントメッセージングにおいて、メッセージを送信したドキュメントのオリジンを表します(通常はドキュメントのスキーム、ホスト名、およびポートですが、パスやフラグメントは含まれません)。
lastEventId 属性は、初期化された値を返さなければなりません。これは、サーバー送信イベントにおいて、イベントソースの最後のイベントID文字列を表します。
source
属性は、初期化された値を返さなければなりません。これは、クロスドキュメントメッセージングにおいて、メッセージが送信されたWindowProxyのブラウジングコンテキストを表します。また、共有ワーカーで使用されるconnectイベントでは、新たに接続するMessagePortを表します。
ports
属性は、初期化された値を返さなければなりません。これは、クロスドキュメントメッセージングおよびチャネルメッセージングにおいて送信されるMessagePort配列を表します。
initMessageEvent(type, bubbles, cancelable, data, origin, lastEventId, source, ports)
メソッドは、同様に命名されたinitEvent()メソッドと同様に、イベントを初期化しなければなりません。[DOM]
様々なAPI(例: WebSocket、EventSource)は、MessageEventインターフェイスを使用してmessageイベントを処理しますが、MessagePortAPIは使用しません。
すべての現在のエンジンでサポートされています。
このセクションは規範的ではありません。
サーバーがHTTPまたは専用のサーバープッシュプロトコルを使用してウェブページにデータをプッシュできるようにするため、この仕様ではEventSourceインターフェイスを導入しています。
このAPIを使用するには、EventSourceオブジェクトを作成し、イベントリスナーを登録します。
var source = new EventSource( 'updates.cgi' );
source. onmessage = function ( event) {
alert( event. data);
};
サーバー側では、スクリプト(この場合は"updates.cgi")が以下の形式でメッセージを送信します。MIMEタイプはtext/event-streamです。
data: これは最初のメッセージです。 data: これは2番目のメッセージで、 data: 2行あります。 data: これは3番目のメッセージです。
作成者は、異なるイベントタイプを使用してイベントを区別できます。ここに2つのイベントタイプ「add」と「remove」を持つストリームがあります。
event: add data: 73857293 event: remove data: 2153 event: add data: 113411
そのようなストリームを処理するスクリプトは次のようになります(addHandlerとremoveHandlerは引数としてイベントを1つ受け取る関数です)。
var source = new EventSource( 'updates.cgi' );
source. addEventListener( 'add' , addHandler, false );
source. addEventListener( 'remove' , removeHandler, false );
デフォルトのイベントタイプは「message」です。
イベントストリームは常にUTF-8でデコードされます。他の文字エンコーディングを指定する方法はありません。
イベントストリームリクエストは、通常のHTTPリクエストと同様にHTTP 301および307リダイレクトを使用してリダイレクトできます。接続が閉じられた場合、クライアントは再接続します。HTTP 204 No Contentレスポンスコードを使用して、クライアントに再接続を停止させることができます。
このAPIを使用することで、XMLHttpRequestやiframeを使用してエミュレートするよりも、ユーザーエージェントがネットワークリソースをより効果的に利用できるようになります。特に、ユーザーエージェントの実装者とネットワークオペレーターが事前に調整することが可能な場合には、特にバッテリー寿命の大幅な節約などの利点があります。これについては、以下の接続なしプッシュセクションでさらに詳しく説明します。
EventSource インターフェイスすべての現在のエンジンでサポートされています。
[Exposed =(Window ,Worker )]
interface EventSource : EventTarget {
constructor (USVString url , optional EventSourceInit eventSourceInitDict = {});
readonly attribute USVString url ;
readonly attribute boolean withCredentials ;
// ready state
const unsigned short CONNECTING = 0;
const unsigned short OPEN = 1;
const unsigned short CLOSED = 2;
readonly attribute unsigned short readyState ;
// networking
attribute EventHandler onopen ;
attribute EventHandler onmessage ;
attribute EventHandler onerror ;
undefined close ();
};
dictionary EventSourceInit {
boolean withCredentials = false ;
};
各 EventSource
オブジェクトには、次のものが関連付けられています。
構築時に設定される url(URL レコード)。
リクエスト。これは初期状態では null でなければなりません。
ミリ秒単位の 再接続時間。これは初期状態では 実装依存の 値でなければならず、おそらく数秒程度の範囲内に設定されます。
最後のイベントID文字列。これは初期状態では空の文字列でなければなりません。
urlを除いて、これらは現在EventSourceオブジェクトに公開されていません。
source = new EventSource(url [, { withCredentials: true } ])
すべての現在のエンジンでサポートされています。
新しいEventSourceオブジェクトを作成します。
urlは、イベントストリームを提供するURLを示す文字列です。
withCredentialsをtrueに設定すると、クレデンシャルモードがurlへの接続リクエストのために"include"に設定されます。
source.close()
すべての現在のエンジンでサポートされています。
このEventSourceオブジェクトに対して開始されたすべてのfetchアルゴリズムのインスタンスを中止し、readyState属性をCLOSEDに設定します。
source.url
すべての現在のエンジンでサポートされています。
イベントストリームを提供するURLを返します。
source.withCredentials
すべての現在のエンジンでサポートされています。
接続リクエストのためのクレデンシャルモードがincludeに設定されている場合にtrueを返し、そうでない場合はfalseを返します。
source.readyState
すべての現在のエンジンでサポートされています。
このEventSourceオブジェクトの接続状態を返します。下記に説明される値を持つことができます。
EventSource(url, eventSourceInitDict)コンストラクタが呼び出されたとき、次の手順を実行しなければなりません。
evを新しいEventSourceオブジェクトにします。
settingsをevの関連する設定オブジェクトにします。
urlRecordをURLのエンコーディングとパースの結果にし、urlをsettingsに相対的にします。
もしurlRecordが失敗なら、"SyntaxError"のDOMExceptionをスローします。
evのurlをurlRecordに設定します。
corsAttributeStateをAnonymousにします。
もしeventSourceInitDictのwithCredentialsメンバーの値がtrueであれば、corsAttributeStateをUse
Credentialsに設定し、evのwithCredentials属性をtrueに設定します。
requestを潜在的なCORSリクエストの作成の結果にし、urlRecord、空文字列、およびcorsAttributeStateを渡します。
requestのクライアントをsettingsに設定します。
ユーザーエージェントはrequestのヘッダーリストにAccept、text/event-streamを設定することがあります。
requestのキャッシュモードを"no-store"に設定します。
requestのイニシエータタイプを"other"に設定します。
evのリクエストをrequestに設定します。
processEventSourceEndOfBodyを次のステップにします。レスポンスのresがネットワークエラーでない場合、接続を再確立します。
Fetchにrequestを指定し、processResponseEndOfBodyをprocessEventSourceEndOfBodyに設定し、processResponseを次のステップに設定します。
もしresが中断されたネットワークエラーであれば、接続を失敗させます。
それ以外の場合、resがネットワークエラーである場合、ユーザーエージェントが無駄だとわかっていない限り、接続を再確立し、そうでない場合はユーザーエージェントが接続を失敗させることがあります。
それ以外の場合、resのステータスが200でない場合、またはresのContent-Typeがtext/event-streamでない場合、接続を失敗させます。
evを返します。
url属性のgetterは、このEventSourceオブジェクトのurlのシリアライズを返さなければなりません。
withCredentials属性は、最後に初期化された値を返さなければなりません。オブジェクトが作成されたとき、falseに初期化されなければなりません。
readyState属性は、接続状態を表します。次の値を持つことができます。
CONNECTING(数値値 0)
OPEN(数値値 1)
CLOSED(数値値 2)
close()メソッドが呼び出されました。
オブジェクトが作成されると、readyStateはCONNECTING(0)に設定されなければなりません。接続を処理するために与えられたルールは、値が変わるタイミングを定義します。
close()メソッドは、このEventSourceオブジェクトのために開始されたfetchアルゴリズムのすべてのインスタンスを中止し、readyState属性をCLOSEDに設定しなければなりません。
次のイベントハンドラ(およびそれに対応するイベントハンドライベントタイプ)は、EventSourceインターフェイスを実装するすべてのオブジェクトによって、イベントハンドラIDL属性としてサポートされなければなりません。
| イベントハンドラ | イベントハンドライベントタイプ |
|---|---|
onopen
すべての現在のエンジンでサポートされています。 Firefox6+Safari5+Chrome6+
Opera12+Edge79+ Edge (レガシー)?Internet Explorerサポートされていません Firefox Android45+Safari iOS5+Chrome Android?WebView Android?Samsung Internet?Opera Android12+ | open |
onmessage
すべての現在のエンジンでサポートされています。 Firefox6+Safari5+Chrome6+
Opera12+Edge79+ Edge (レガシー)?Internet Explorerサポートされていません Firefox Android45+Safari iOS5+Chrome Android?WebView Android?Samsung Internet?Opera Android12+ | message |
onerror
すべての現在のエンジンでサポートされています。 Firefox6+Safari5+Chrome6+
Opera12+Edge79+ Edge (レガシー)?Internet Explorerサポートされていません Firefox Android45+Safari iOS5+Chrome Android?WebView Android?Samsung Internet?Opera Android12+ | error |
ユーザーエージェントが接続をアナウンスする場合、ユーザーエージェントはタスクをキューに入れる必要があります。このとき、readyState属性がCLOSED以外の値に設定されている場合、readyState属性をOPENに設定し、「open」という名前のイベントを発火させ、EventSourceオブジェクトにイベントを発火させます。
ユーザーエージェントが接続を再確立する場合、次の手順を実行する必要があります。これらの手順は並行して実行され、タスクの一部として実行されません。(もちろん、キューに入れられたタスクは通常のタスクのように実行され、それ自体が並行して実行されるわけではありません。)
タスクをキューに入れることによって次のステップを実行します。
readyState属性がCLOSEDに設定されている場合、タスクを中止します。
readyState属性をCONNECTINGに設定します。
イベントを発火させ、errorという名前のイベントをEventSourceオブジェクトに対して発火させます。
イベントソースの再接続時間と同等の遅延を待ちます。
必要に応じて、さらに待ちます。特に、前回の試行が失敗した場合、ユーザーエージェントは、既に過負荷の可能性があるサーバーを過負荷にしないように指数バックオフ遅延を導入するかもしれません。あるいは、オペレーティングシステムがネットワーク接続がないと報告している場合、ユーザーエージェントは、ネットワーク接続が復旧したとオペレーティングシステムが発表するまで待つかもしれません。
前述のタスクがまだ実行されていない場合、そのタスクが実行されるまで待ちます。
タスクをキューに入れることによって次のステップを実行します。
EventSourceオブジェクトのreadyState属性がCONNECTINGに設定されていない場合、終了します。
requestをEventSourceオブジェクトのリクエストとします。
EventSourceオブジェクトの最後のイベントID文字列が空でない場合は次の操作を行います。
lastEventIDValueを、EventSourceオブジェクトの最後のイベントID文字列として、UTF-8でエンコードされた文字列とします。
「Last-Event-ID」 (`Last-Event-ID`,
lastEventIDValue)をrequestのヘッダーリストに設定します。
リクエストをフェッチし、この方法で取得したレスポンスを処理します(もしあれば)、このセクションで前述のとおりに処理します。
ユーザーエージェントが接続を失敗させる場合、ユーザーエージェントはタスクをキューに入れる必要があり、その際にreadyState属性がCLOSEDに設定されていない場合は、それをreadyState属性にCLOSEDに設定し、イベントを発火させerrorという名前のイベントをEventSourceオブジェクトに対して行います。
一度ユーザーエージェントが接続を失敗させた場合、それは再接続しません。
EventSourceオブジェクトによってキューに入れられたすべてのタスクのタスクソースは、リモートイベントタスクソースです。
Last-Event-ID` ヘッダーLast-Event-ID` HTTPリクエストヘッダーは、ユーザーエージェントが接続を再確立する際に、EventSourceオブジェクトの最後のイベントID文字列をサーバーに報告します。
whatwg/html issue #7363を参照して、値の空間をより適切に定義してください。それは本質的には、U+0000 NULL、U+000A LF、またはU+000D CRを含まないUTF-8でエンコードされた任意の文字列です。
このイベントストリーム形式のMIMEタイプは、text/event-streamです。
イベントストリーム形式は、次のABNFのstream生成によって記述されており、その文字セットはUnicodeです。[ABNF]
stream = [ bom ] * event
event = * ( comment / field ) end-of-line
comment = colon * any-char end-of-line
field = 1* name-char [ colon [ space ] * any-char ] end-of-line
end-of-line = ( cr lf / cr / lf )
; characters
lf = %x000A ; U+000A LINE FEED (LF)
cr = %x000D ; U+000D CARRIAGE RETURN (CR)
space = %x0020 ; U+0020 SPACE
colon = %x003A ; U+003A COLON (:)
bom = %xFEFF ; U+FEFF BYTE ORDER MARK
name-char = %x0000-0009 / %x000B-000C / %x000E-0039 / %x003B-10FFFF
; a scalar value other than U+000A LINE FEED (LF), U+000D CARRIAGE RETURN (CR), or U+003A COLON (:)
any-char = %x0000-0009 / %x000B-000C / %x000E-10FFFF
; a scalar value other than U+000A LINE FEED (LF) or U+000D CARRIAGE RETURN (CR)
この形式のイベントストリームは常にUTF-8でエンコードされる必要があります。[ENCODING]
行は、U+000DキャリッジリターンU+000Aラインフィード(CRLF)文字ペア、単一のU+000Aラインフィード(LF)文字、または単一のU+000Dキャリッジリターン(CR)文字で区切られる必要があります。
このようなリソースに対してリモートサーバーへの接続が長時間続くことが期待されるため、ユーザーエージェントは適切なバッファリングを確保する必要があります。特に、単一のU+000Aラインフィード(LF)文字で行が終了するように定義された行バッファリングは安全ですが、ブロックバッファリングや異なる行末を持つ行バッファリングは、イベントの配信に遅延を引き起こす可能性があります。
ストリームは、UTF-8デコードアルゴリズムを使用してデコードされる必要があります。
UTF-8デコードアルゴリズムは、先頭にある1つのUTF-8バイトオーダーマーク(BOM)を、もし存在すれば取り除きます。
次に、ストリームは行ごとに読み取られ、U+000DキャリッジリターンU+000Aラインフィード(CRLF)文字ペア、U+000Dキャリッジリターン(CR)文字が前にない単一のU+000Aラインフィード(LF)文字、またはU+000Aラインフィード(LF)文字が後にない単一のU+000Dキャリッジリターン(CR)文字が行の終わりとして認識されます。
ストリームが解析されるとき、dataバッファ、event typeバッファ、およびlast event IDバッファがそれに関連付けられ、これらは空文字列で初期化される必要があります。
受信順に従って、行は次のように処理される必要があります。
イベントを配信します(以下で定義されている通り)。
行を無視します。
最初のU+003Aコロン文字(:)までの文字を収集し、それをfieldとします。
最初のU+003Aコロン文字(:)の後の文字を収集し、それをvalueとします。valueがU+0020スペース文字で始まる場合、それを取り除きます。
フィールドを処理し、fieldをフィールド名として、valueをフィールド値として使用します。
行全体をフィールド名として使用し、空文字列をフィールド値としてフィールドを処理します。
ファイルの終わりに達したら、保留中のデータは破棄される必要があります。(ファイルがイベントの途中で終了した場合、最後の空行の前に、不完全なイベントは配信されません。)
フィールド名とフィールド値が与えられた場合のフィールドを処理する手順は、以下のリストに記載されたフィールド名に依存します。フィールド名は、大小文字を区別して比較される必要があります。
event typeバッファをフィールド値に設定します。
フィールド値をdataバッファに追加し、次に単一のU+000Aラインフィード(LF)文字をdataバッファに追加します。
フィールド値にU+0000 NULLが含まれていない場合は、last event IDバッファをフィールド値に設定します。それ以外の場合は、フィールドを無視します。
フィールド値がASCII数字のみで構成されている場合、フィールド値を10進数の整数として解釈し、イベントストリームの再接続時間をその整数に設定します。それ以外の場合は、フィールドを無視します。
フィールドは無視されます。
ユーザーエージェントがイベントを配信する必要がある場合、ユーザーエージェントはdataバッファ、event typeバッファ、およびlast event IDバッファを、ユーザーエージェントに適した手順を使用して処理する必要があります。
ウェブブラウザーにとって、イベントを配信するための適切な手順は以下の通りです。
イベントソースの最終イベントID文字列をlast event IDバッファの値に設定します。このバッファはリセットされないため、イベントソースの最終イベントID文字列は、次回サーバーによって設定されるまでこの値のまま残ります。
dataバッファが空文字列である場合、dataバッファとevent typeバッファを空文字列に設定し、終了します。
dataバッファの最後の文字がU+000Aラインフィード(LF)文字である場合、dataバッファから最後の文字を削除します。
eventをイベントを作成する結果として生成し、そのインターフェースをMessageEventとします。
eventのtype属性を「message」に設定し、data属性をdata、origin属性をイベントストリームの最終URLのシリアル化に設定し、lastEventId属性をイベントソースの最終イベントID文字列に設定します。
event typeバッファが空文字列以外の値を持っている場合、新しく作成されたイベントのtypeをevent typeバッファの値に変更します。
dataバッファとevent typeバッファを空文字列に設定します。
タスクをキューに入れることによって、readyState属性がCLOSED以外の値に設定されている場合、新しく作成されたイベントをイベントソースに配信します。
イベントに「id」フィールドがない場合でも、以前のイベントがイベントソースの最終イベントID文字列を設定した場合、イベントのlastEventIdフィールドは、最後に見られた「id」フィールドの値に設定されます。
次のイベントストリームは、空行の後に続くと:
data: YHOO data: +2 data: 10
...イベントがmessageとして、MessageEventインターフェースを持つイベントがEventSourceオブジェクト上で配信されます。イベントのdata属性には、文字列"YHOO\n+2\n10"("\n"は改行を表します)が含まれます。
これを次のように使用できます:
var stocks = new EventSource( "https://stocks.example.com/ticker.php" );
stocks. onmessage = function ( event) {
var data = event. data. split( '\n' );
updateStocks( data[ 0 ], data[ 1 ], data[ 2 ]);
};
...ここで、updateStocks()は次のように定義された関数です:
function updateStocks( symbol, delta, value) { ... }
...またはそのようなものです。
次のストリームには4つのブロックが含まれています。最初のブロックにはコメントしかなく、何も発生しません。2番目のブロックには、それぞれ"data"と"id"という名前のフィールドが2つあります。このブロックに対してイベントが発生し、データ"first
event"を持ち、その後に最終イベントIDが"1"に設定されます。このブロックと次のブロックの間で接続が切れた場合、サーバーには`Last-Event-ID`ヘッダーが値`1`で送信されます。3番目のブロックはデータ"second
event"を持つイベントを発生させ、今回は値のない"id"フィールドも含まれています。これにより最終イベントIDが空文字列にリセットされます(再接続が試みられた場合、`Last-Event-ID`ヘッダーは送信されません)。最後に、最後のブロックはデータ"
third event"(先頭に1つのスペース文字がある)を持つイベントを発生させます。最後のブロックは空行で終了する必要があり、ストリームの終了だけでは最後のイベントを配信するのに十分ではありません。
: test stream data: first event id: 1 data:second event id data: third event
次のストリームは2つのイベントを発生させます:
data data data data:
最初のブロックはデータが空文字列に設定されたイベントを発生させます。同様に最後のブロックも、もしそれが空行の後に続いていた場合は同じです。中央のブロックはデータが1つの改行文字に設定されたイベントを発生させます。最後のブロックは空行が続かないため破棄されます。
次のストリームは2つの同一のイベントを発生させます:
data:test data: test
これは、コロンの後のスペースが存在する場合に無視されるためです。
レガシープロキシサーバーは、特定のケースで短時間のタイムアウト後にHTTP接続を切断することが知られています。そのようなプロキシサーバーから保護するために、作成者は約15秒ごとにコメント行(':'文字で始まる行)を含めることができます。
イベントソース接続を互いに、または以前に提供された特定のドキュメントに関連付けたい作成者は、IPアドレスに依存することがうまくいかないことを発見するかもしれません。これは、個々のクライアントが複数のIPアドレスを持っている可能性があるためです(複数のプロキシサーバーを使用しているため)。また、個々のIPアドレスが複数のクライアントを持っている可能性もあります(プロキシサーバーを共有しているため)。ドキュメントに一意の識別子を含め、それを接続が確立される際にURLの一部として渡す方が良いでしょう。
作成者はまた、HTTPチャンク化がこのプロトコルの信頼性に予期しない悪影響を与える可能性があることにも注意が必要です。特に、タイミングの要件を認識していない別のレイヤーによってチャンク化が行われる場合です。この問題が発生する場合、イベントストリームの提供にはチャンク化を無効にすることができます。
HTTPのサーバーごとの接続制限をサポートするクライアントは、同じドメインにEventSourceを持つページを複数開くときに問題に直面する可能性があります。作成者は、接続ごとに一意のドメイン名を使用するという比較的複雑なメカニズムを使用するか、ユーザーにページごとにEventSource機能を有効または無効にするオプションを提供するか、共有ワーカーを使用して単一のEventSourceオブジェクトを共有することで、これを回避できます。
特定のキャリアに結びついたモバイル端末上のブラウザなど、制御された環境で実行されるユーザーエージェントは、ネットワーク上のプロキシに接続の管理をオフロードする場合があります。そのような状況では、適合性のために、ユーザーエージェントは端末のソフトウェアとネットワークプロキシの両方を含むと見なされます。
たとえば、モバイルデバイス上のブラウザが接続を確立した後、対応するネットワーク上で動作していることを検出し、ネットワーク上のプロキシサーバーに接続の管理を引き継ぐように要求するかもしれません。このような状況のタイムラインは次のようになります:
EventSourceコンストラクターで作成者によって指定されたリソースを要求します。
EventSourceコンストラクターで作成者によって指定されたリソースを要求します(`Last-Event-ID`HTTPヘッダーなどを含む可能性があります)。
これにより、総データ使用量を削減できるため、大幅な電力節約につながる可能性があります。
この仕様で定義されている既存のAPIおよびtext/event-streamワイヤ形式を、上記のようにより分散された方法で実装することに加えて、他の適用可能な仕様によって定義されたイベントフレーミングの形式もサポートされる場合があります。この仕様では、それらがどのように解析または処理されるかについて定義していません。
EventSourceオブジェクトのreadyStateがCONNECTINGであり、オブジェクトにopen、message、またはerrorイベントのイベントリスナーが1つ以上登録されている場合、EventSourceオブジェクトのコンストラクターが呼び出されたWindowまたはWorkerGlobalScopeオブジェクトからそのEventSourceオブジェクト自体への強い参照が存在しなければなりません。
EventSourceオブジェクトのreadyStateがOPENであり、オブジェクトにmessageまたはerrorイベントのイベントリスナーが1つ以上登録されている場合、EventSourceオブジェクトのコンストラクターが呼び出されたWindowまたはWorkerGlobalScopeオブジェクトからそのEventSourceオブジェクト自体への強い参照が存在しなければなりません。
EventSourceオブジェクトによってリモートイベントタスクソースにタスクがキューに入れられている間は、EventSourceオブジェクトのコンストラクターが呼び出されたWindowまたはWorkerGlobalScopeオブジェクトからそのEventSourceオブジェクトへの強い参照が存在しなければなりません。
ユーザーエージェントがEventSourceオブジェクトを強制的に閉じる必要がある場合(これはDocumentオブジェクトが永久に消えるときに発生します)、ユーザーエージェントはこのEventSourceオブジェクトのために開始されたfetchアルゴリズムのインスタンスをすべて中止し、readyState属性をCLOSEDに設定しなければなりません。
接続がまだ開いている間にEventSourceオブジェクトがガベージコレクションされる場合、ユーザーエージェントはこのEventSourceによって開かれたfetchアルゴリズムのインスタンスをすべて中止しなければなりません。
このセクションは規範的ではありません。
ユーザーエージェントは、EventSourceオブジェクトとそれに関連するネットワーク接続に関する詳細な診断情報を開発コンソールに提供し、このAPIを使用してコードをデバッグする際に作成者を支援することを強く推奨します。
たとえば、ユーザーエージェントはページが作成したすべてのEventSourceオブジェクトを表示するパネルを持ち、各オブジェクトのコンストラクタ引数、ネットワークエラーの有無、接続のCORSステータス、そのステータスに至るまでにクライアントが送信したヘッダーとサーバーから受信したヘッダー、受信したメッセージとそれらがどのように解析されたかなどを一覧表示することができます。
特に、errorイベントが発生するたびに、開発コンソールに詳細な情報を報告することが強く推奨されます。イベント自体にはほとんど情報が含まれないか、まったく情報が含まれない可能性があるためです。
Support in all current engines.
Webブラウザは、セキュリティとプライバシーの理由から、異なるドメインのドキュメントが互いに影響を与えることを防ぎます。つまり、クロスサイトスクリプティングは許可されていません。
これは重要なセキュリティ機能ですが、敵対的でないページ間でも異なるドメインのページが通信できなくなります。このセクションでは、クロスサイトスクリプティング攻撃を可能にしない方法で、ソースドメインに関係なくドキュメント同士が通信できるメッセージングシステムを紹介します。
postMessage() APIは、トラッキングベクターとして使用される可能性があります。
このセクションは規範的ではありません。
例えば、ドキュメントAがiframe要素を含んでおり、その中にドキュメントBが含まれている場合、ドキュメントAのスクリプトがドキュメントBのWindowオブジェクトに対してpostMessage()を呼び出すと、そのオブジェクト上でメッセージイベントが発生し、それがドキュメントAのWindowから発信されたことが示されます。ドキュメントAのスクリプトは次のようになるかもしれません:
var o = document. getElementsByTagName( 'iframe' )[ 0 ];
o. contentWindow. postMessage( 'Hello world' , 'https://b.example.org/' );
受信イベントのイベントハンドラーを登録するには、スクリプトはaddEventListener()(または同様のメカニズム)を使用します。例えば、ドキュメントBのスクリプトは次のようになるかもしれません:
window. addEventListener( 'message' , receiver, false );
function receiver( e) {
if ( e. origin == 'https://example.com' ) {
if ( e. data == 'Hello world' ) {
e. source. postMessage( 'Hello' , e. origin);
} else {
alert( e. data);
}
}
}
このスクリプトはまず、ドメインが期待されたドメインであることを確認し、その後メッセージを確認して、それをユーザーに表示するか、メッセージを最初に送信したドキュメントに返信するかを決定します。
このAPIの使用には、悪意のある者がサイトを自分の目的のために悪用するのを防ぐために、特に注意が必要です。
作成者は、メッセージが予期されるドメインからのみ受信されるように、origin属性を確認する必要があります。そうしないと、作成者のメッセージ処理コードのバグが悪意のあるサイトによって悪用される可能性があります。
さらに、origin属性を確認した後でも、問題のデータが期待された形式であることを確認する必要があります。そうしないと、イベントのソースがクロスサイトスクリプティングの欠陥を利用して攻撃された場合、postMessage()メソッドを使用して送信された情報のさらなる未チェックの処理が、攻撃を受信者に伝播させる可能性があります。
作成者は、機密情報を含むメッセージのtargetOrigin引数にワイルドカードキーワード(*)を使用すべきではありません。そうしないと、メッセージが意図した受信者にのみ配信されることを保証する方法がなくなります。
任意のオリジンからのメッセージを受け入れる作成者は、サービス拒否攻撃のリスクを考慮することが奨励されます。攻撃者は大量のメッセージを送信する可能性があります。受信ページが各メッセージに対して高価な計算を行ったり、ネットワークトラフィックを発生させたりする場合、攻撃者のメッセージがサービス拒否攻撃に発展する可能性があります。作成者は、このような攻撃を非現実的にするために、レート制限(1分あたり一定数のメッセージのみを受け入れる)を採用することが奨励されます。
このAPIの整合性は、あるオリジンのスクリプトが他のオリジン(同一オリジンではないオリジン)に属するオブジェクトに対して任意のイベントを(dispatchEvent()などを使用して)投稿できないという事実に基づいています。
実装者は、この機能の実装に際して特に注意を払うよう強く促されます。この機能は、通常セキュリティ上の理由で許可されていない、あるドメインから別のドメインへの情報の送信を作成者に許可するものです。また、ユーザーエージェントは特定のプロパティにはアクセスを許可し、他のプロパティには許可しないよう慎重である必要があります。
ユーザーエージェントはまた、異なるオリジン間のメッセージトラフィックに対してレート制限を検討することが奨励されます。これは、ナイーブなサイトをサービス拒否攻撃から保護するためです。
window.postMessage(message [, options ])
Support in all current engines.
指定されたウィンドウにメッセージを投稿します。メッセージには構造化されたオブジェクト(ネストされたオブジェクトや配列など)を含めることができ、JavaScriptの値(文字列、数値、Dateオブジェクトなど)を含めることができ、File、Blob、FileList、ArrayBufferオブジェクトなどの特定のデータオブジェクトを含むことができます。
optionsのtransferメンバーにリストされているオブジェクトは、単にクローンされるのではなく、転送されるため、送信側ではもはや使用できません。
optionsのtargetOriginメンバーを使用して、ターゲットオリジンを指定できます。指定されていない場合、デフォルトは"/"です。このデフォルトは、メッセージを同一オリジンのターゲットにのみ制限します。
ターゲットウィンドウのオリジンが指定されたターゲットオリジンと一致しない場合、情報漏洩を防ぐためにメッセージは破棄されます。オリジンに関係なくメッセージをターゲットに送信するには、ターゲットオリジンを"*"に設定します。
次の条件に該当する場合、"DataCloneError" DOMException
をスローします: transfer 配列に重複するオブジェクトが含まれている場合、または message がクローンできなかった場合。
window.postMessage(message, targetOrigin [, transfer ])
こちらはpostMessage()の別バージョンで、ターゲットオリジンがパラメータとして指定されます。window.postMessage(message, target, transfer)を呼び出すことは、window.postMessage(message, {targetOrigin, transfer})と同等です。
新しいDocumentにナビゲートされたばかりのbrowsing contextのWindowにメッセージを送信すると、メッセージが意図された受信者に届かない可能性が高くなります。これは、ターゲットのbrowsing
contextのスクリプトがメッセージのリスナーを設定する時間を持たなければならないからです。したがって、例えば、新しく作成された子iframeのWindowにメッセージを送信するような状況では、子Documentが親にメッセージを送信してメッセージを受信する準備ができたことを知らせ、親がメッセージの送信を開始する前にこのメッセージを待つことを作成者に勧めます。
window post message stepsは、targetWindow、message、およびoptionsが与えられた場合に次のように実行されます:
targetRealmをtargetWindowのrealmとします。
incumbentSettingsをインカンベント設定オブジェクトとします。
targetOriginをoptions["targetOrigin"]とします。
targetOriginが単一のU+002F SOLIDUS文字(/)である場合、targetOriginをincumbentSettingsのoriginに設定します。
そうでない場合、targetOriginが単一のU+002A ASTERISK文字(*)でない場合は:
parsedURL を、targetOrigin に対してURL パーサーを実行した結果とします。
parsedURL が失敗である場合、"SyntaxError" DOMException
をスローします。
targetOrigin を parsedURL の origin に設定します。
transferをoptions["transfer"]とします。
serializeWithTransferResultをStructuredSerializeWithTransfer(message, transfer)とし、例外を再スローします。
targetWindowに与えられた投稿されたメッセージタスクソースに対して、次のステップを実行するためにグローバルタスクをキューに入れます:
targetOrigin引数が単一のリテラルU+002A ASTERISK文字(*)でない場合、およびtargetWindowの関連するDocumentのoriginがtargetOriginと同一オリジンでない場合、戻ります。
originをincumbentSettingsのoriginのシリアル化とします。
sourceを、incumbentSettingsのグローバルオブジェクト(Windowオブジェクト)に対応するWindowProxyオブジェクトとします。
deserializeRecordをStructuredDeserializeWithTransfer(serializeWithTransferResult, targetRealm)とします。
これにより例外がスローされた場合、それをキャッチし、MessageEventを使用してtargetWindowでmessageerrorという名前のイベントを発火させ、origin属性をoriginに初期化し、source属性をsourceに初期化してから戻ります。
messageCloneをdeserializeRecord.[[Deserialized]]とします。
newPortsを、deserializeRecord.[[TransferredValues]]に含まれるすべてのMessagePortオブジェクトで構成される新しいフローズン配列とし、それらの相対的な順序を維持します。
MessageEventを使用してtargetWindowでmessageという名前のイベントを発火させ、origin属性をoriginに初期化し、source属性をsourceに初期化し、data属性をmessageCloneに初期化し、ports属性をnewPortsに初期化します。
WindowインターフェースのpostMessage(message, options)メソッドのステップは、window post message
stepsをthis、message、およびoptionsを使用して実行することです。
WindowインターフェースのpostMessage(message, targetOrigin, transfer)メソッドのステップは、window post message
stepsをthis、message、および「["targetOrigin"→targetOrigin、"transfer"→transfer]」を使用して実行することです。
すべての現在のエンジンでサポートされています。
Channel_Messaging_API/Using_channel_messaging
すべての現在のエンジンでサポートされています。
このセクションは規範的ではありません。
独立したコード片(例:異なるブラウジングコンテキストで実行される)同士が直接通信できるようにするため、作成者はチャンネルメッセージングを使用できます。
このメカニズムの通信チャネルは双方向パイプとして実装されており、各端にポートがあります。一方のポートで送信されたメッセージは、もう一方のポートで受信され、その逆も同様です。メッセージはDOMイベントとして配信され、実行中のタスクを中断したりブロックしたりすることなく配信されます。
接続(2つの「絡み合った」ポート)を作成するには、MessageChannel()コンストラクタを呼び出します:
var channel = new MessageChannel();
ポートの1つはローカルポートとして保持され、もう一方のポートはリモートコードに送信されます。例えば、postMessage()を使用して:
otherWindow. postMessage( 'hello' , 'https://example.com' , [ channel. port2]);
メッセージを送信するには、ポート上のpostMessage()メソッドを使用します:
channel. port1. postMessage( 'hello' );
メッセージを受信するには、messageイベントをリッスンします:
channel. port1. onmessage = handleMessage;
function handleMessage( event) {
// メッセージは event.data に含まれています
// ...
}
ポート上で送信されるデータは構造化データにすることができます。例えば、ここでは文字列の配列がMessagePortで渡されます:
port1. postMessage([ 'hello' , 'world' ]);
このセクションは規範的ではありません。
この例では、2つのJavaScriptライブラリがMessagePortを使用して互いに接続されています。これにより、後でライブラリが異なるフレームやWorkerオブジェクトでホストされるようになっても、APIを変更することなく動作します。
< script src = "contacts.js" ></ script > <!-- contacts オブジェクトを公開します -->
< script src = "compose-mail.js" ></ script > <!-- composer オブジェクトを公開します -->
< script >
var channel = new MessageChannel();
composer. addContactsProvider( channel. port1);
contacts. registerConsumer( channel. port2);
</ script >
「addContactsProvider()」関数の実装は以下のようになります:
function addContactsProvider( port) {
port. onmessage = function ( event) {
switch ( event. data. messageType) {
case 'search-result' : handleSearchResult( event. data. results); break ;
case 'search-done' : handleSearchDone(); break ;
case 'search-error' : handleSearchError( event. data. message); break ;
// ...
}
};
};
または、次のように実装することもできます:
function addContactsProvider( port) {
port. addEventListener( 'message' , function ( event) {
if ( event. data. messageType == 'search-result' )
handleSearchResult( event. data. results);
});
port. addEventListener( 'message' , function ( event) {
if ( event. data. messageType == 'search-done' )
handleSearchDone();
});
port. addEventListener( 'message' , function ( event) {
if ( event. data. messageType == 'search-error' )
handleSearchError( event. data. message);
});
// ...
port. start();
};
主な違いは、addEventListener()を使用する場合、start()メソッドも呼び出す必要がある点です。onmessageを使用する場合、start()の呼び出しは暗黙的に行われます。
start()メソッドは、明示的に呼び出される場合でも、暗黙的に呼び出される場合でも、メッセージの流れを開始します:メッセージポートで送信されたメッセージは最初は一時停止され、スクリプトがハンドラを設定する前にメッセージが失われることがないようにします。
このセクションは規範的ではありません。
ポートは、システム内の他のアクターに対して限られた能力(オブジェクト能力モデルの意味で)を公開する方法と見なすことができます。これは、単に特定のオリジン内で便利なモデルとしてポートを使用する弱い能力システムである場合もあれば、1つのオリジンproviderが他のオリジンconsumerに対して変更を加えたり、providerから情報を取得したりする唯一のメカニズムとして提供する強力な能力モデルである場合もあります。
例えば、ソーシャルWebサイトが1つのiframeにユーザーのメール連絡先プロバイダー(別のオリジンのアドレス帳サイト)を埋め込み、別のiframeにゲーム(第三のオリジンから)を埋め込む状況を考えてみてください。外側のソーシャルサイトと2番目のiframe内のゲームは、最初のiframe内の何かにアクセスすることはできません。両者ができるのは、次のことだけです:
ナビゲートして、iframeを新しいURL、例えば異なるURLだが異なるフラグメントを含むURLに移動させ、Windowにhashchangeイベントを受信させる。
messageイベントをWindowにwindow.postMessage()APIを使用して送信する。
連絡先プロバイダーは、これらの方法、特に3つ目の方法を使用して、他のオリジンがユーザーのアドレス帳を操作できるAPIを提供できます。例えば、「add-contact Guillaume Tell <tell@pomme.example.net>」というメッセージに応答して、指定された人物とメールアドレスをユーザーのアドレス帳に追加することができます。
任意のサイトがユーザーの連絡先を操作できないようにするために、連絡先プロバイダーは特定の信頼できるサイト(例えばソーシャルサイト)のみがこれを行えるようにすることがあります。
さて、ゲームがユーザーのアドレス帳に連絡先を追加したい場合で、ソーシャルサイトがそれを代理で許可したいと仮定します。これにより、連絡先プロバイダーがソーシャルサイトに持っている信頼をゲームと「共有」することになります。これを行うにはいくつかの方法があります。最も単純な方法は、ソーシャルサイトがゲームサイトと連絡先サイトの間でメッセージをプロキシすることです。しかし、この解決策にはいくつかの問題があります。ソーシャルサイトがゲームサイトを完全に信頼して特権を乱用しないことを保証する必要があるか、ソーシャルサイトが各リクエストを検証して、複数の連絡先を追加する、連絡先を読み取る、または削除するなど許可したくないリクエストを防ぐ必要があります。また、複数のゲームが同時に連絡先プロバイダーとやり取りしようとする可能性がある場合には、追加の複雑さが必要になります。
しかし、メッセージチャネルとMessagePortオブジェクトを使用すれば、これらの問題はすべて解決できます。ゲームが連絡先を追加したいとソーシャルサイトに伝えると、ソーシャルサイトは連絡先を追加するように連絡先プロバイダーに要求するのではなく、単一の連絡先を追加する能力を求めます。連絡先プロバイダーは、MessagePortオブジェクトのペアを作成し、そのうちの1つをソーシャルサイトに送り返し、ソーシャルサイトはそれをゲームに転送します。これにより、ゲームと連絡先プロバイダーは直接接続され、連絡先プロバイダーは単一の「連絡先追加」リクエストのみを受け付け、それ以外は受け付けないことを認識します。言い換えれば、ゲームは単一の連絡先を追加する能力を付与されたことになります。
このセクションは規範的ではありません。
前のセクションの例を続けて、特に連絡先プロバイダーについて考えてみます。初期の実装では、単にサービスのXMLHttpRequestオブジェクトを使用し、iframe内でサービスを提供していたかもしれませんが、サービスの進化に伴い、共有ワーカーと単一のWebSocket接続を使用したいと考えるかもしれません。
初期設計でMessagePortオブジェクトを使用して能力を付与したり、複数の同時独立セッションを許可したりしていた場合、サービス実装はXMLHttpRequests-in-each-iframeモデルから、共有WebSocketモデルに変更することができ、APIをまったく変更せずに済みます。サービスプロバイダー側のポートはすべて共有ワーカーに転送でき、それがAPIのユーザーに何の影響も与えません。
すべての主要エンジンでサポートされています。
[Exposed =(Window ,Worker )]
interface MessageChannel {
constructor ();
readonly attribute MessagePort port1 ;
readonly attribute MessagePort port2 ;
};
channel = new MessageChannel()
すべての主要エンジンでサポートされています。
2つの新しいMessagePortオブジェクトを持つ新しいMessageChannelオブジェクトを返します。
channel.port1
すべての主要エンジンでサポートされています。
最初のMessagePortオブジェクトを返します。
channel.port2
すべての主要エンジンでサポートされています。
2番目のMessagePortオブジェクトを返します。
MessageChannel オブジェクトには、ポート1とポート2という、どちらもMessagePortオブジェクトが関連付けられています。
new MessageChannel() コンストラクタの手順は次のとおりです:
port1
ゲッターの手順は、this の
ポート1 を返します。
port2
ゲッターの手順は、this の
ポート2 を返します。
すべての最新エンジンでサポートされています。
各チャネルには2つのメッセージポートがあります。一方のポートで送信されたデータはもう一方のポートで受信され、その逆も可能です。
[Exposed =(Window ,Worker ,AudioWorklet ), Transferable ]
interface MessagePort : EventTarget {
undefined postMessage (any message , sequence <object > transfer );
undefined postMessage (any message , optional StructuredSerializeOptions options = {});
undefined start ();
undefined close ();
// イベントハンドラ
attribute EventHandler onmessage ;
attribute EventHandler onmessageerror ;
attribute EventHandler onclose ;
};
dictionary StructuredSerializeOptions {
sequence <object > transfer = [];
};
port.postMessage(message [, transfer])
すべての最新エンジンでサポートされています。
チャネルを通してメッセージを送信します。transferにリストされたオブジェクトは、クローンされるのではなく転送され、送信側では使用できなくなります。
transferに重複するオブジェクトやportが含まれている場合、またはmessageをクローンできなかった場合、"DataCloneError" DOMException
をスローします。
port.start()
すべての最新エンジンでサポートされています。
ポートで受信したメッセージのディスパッチを開始します。
port.close()
すべての最新エンジンでサポートされています。
ポートを切断し、それを非アクティブにします。
各 MessagePort
オブジェクトは、別のオブジェクトと連結(対称的な関係)されることができます。
各 MessagePort オブジェクトは、最初は空のタスクソースであるポートメッセージキューを持っています。
ポートメッセージキューは、有効化または無効化できますが、初期状態では無効です。一度有効化されると、ポートは再び無効化されることはありません(ただし、キュー内のメッセージは別のキューに移動したり、完全に削除されたりすることがあり、これはほぼ同じ効果を持ちます)。
MessagePort には、出荷済み フラグもあり、最初は false に設定されます。
ポートのポートメッセージキューが有効化されると、イベントループは、それをタスクソースの1つとして使用しなければなりません。
ポートの 関連グローバルオブジェクトが Window である場合、そのポートの ポートメッセージキューにキューされたすべての タスクは、そのポートの関連グローバルオブジェクトに関連付けられた Documentに関連付けられなければなりません。
ドキュメントが完全にアクティブであっても、イベントリスナーがすべて完全にアクティブでないドキュメントのコンテキストで作成された場合、ドキュメントが再び完全にアクティブになるまでメッセージは受信されません。
各イベントループには、タスクソースと呼ばれる未出荷ポートメッセージキューがあります。これは仮想的なタスクソースです。
これは、出荷済みフラグが false であり、ポートメッセージキューが有効で、その関連エージェントのイベントループがそのイベントループである各 MessagePort
のポートメッセージキューのタスクを含んでいるかのように動作しなければなりません。
各タスクがそれぞれのタスクソースに追加された順序で、このタスクソースに含まれるべきです。タスクが未出荷ポートメッセージキューから削除される場合、それは代わりにそのポートメッセージキューから削除されなければなりません。
MessagePort の出荷済みフラグが false
である場合、そのポートメッセージキューはイベントループの目的において無視されなければなりません。(未出荷ポートメッセージキューが代わりに使用されます。)
出荷済みフラグは、ポート、そのツイン、またはクローンされたオブジェクトが転送されるかされた場合に true に設定されます。MessagePortの出荷済みフラグが true
の場合、そのポートメッセージキューは、未出荷ポートメッセージキューの影響を受けずに一級のタスクソースとして機能します。
ユーザーエージェントが二つのMessagePortオブジェクトを絡め合うとき、それは次のステップを実行しなければならない:
片方のポートが既に絡め合っている場合、それを解き、絡め合っていたポートを解く。
以前に絡め合っていた二つのポートがMessageChannelオブジェクトの二つのポートであった場合、そのMessageChannelオブジェクトはもはや実際のチャネルを表さなくなる:そのオブジェクト内の二つのポートはもはや絡め合っていない。
絡め合うべき二つのポートを関連付け、新しいチャネルの二つの部分を形成するようにする。(このチャネルを表すMessageChannelオブジェクトは存在しない。)
このステップを経たポートAとBは、互いに絡め合っていると言われ、一方が他方に絡め合っている状態である。
この仕様ではこのプロセスを瞬時に行うものとして記述しているが、実装はメッセージのやり取りによって実装される可能性が高い。すべてのアルゴリズムと同様に、重要なのは最終的な結果が仕様から見てブラックボックス的に区別できないことである。
MessagePortを開始したinitiatorPortに対して、解きほぐすステップは次の通りである:
initiatorPortが絡め合っていたMessagePortをotherPortとする。
確認:otherPortが存在すること。
initiatorPortとotherPortを解きほぐし、これ以上絡め合わず、互いに関連付けられなくする。
イベントを発生させる名前付き閉じるイベントをotherPortで発生させる。
この閉じるイベントは、ポートが明示的に閉じられていない場合でも発生する。このイベントが発生するケースは次の通りである:
close()メソッドが呼び出された場合;
Documentが破棄された場合;MessagePortがガベージコレクションされた場合。このイベントはotherPortでのみ発生する。なぜならinitiatorPortが明示的に閉じることをトリガーしたか、そのDocumentが存在しなくなったか、または既にガベージコレクションされたためである。
MessagePortオブジェクトは転送可能なオブジェクトです。次の転送手順に従います。
valueの配送済みフラグを真に設定します。
dataHolderの[[PortMessageQueue]]にvalueのポートメッセージキューを設定します。
valueが他のポートremotePortと絡め合っている場合:
remotePortの配送済みフラグを真に設定します。
dataHolderの[[RemotePort]]にremotePortを設定します。
それ以外の場合、dataHolderの[[RemotePort]]をnullに設定します。
次に、受信側の転送手順に従います:
valueの配送済みフラグを真に設定します。
すべてのタスクを、dataHolderの[[PortMessageQueue]]からvalueのポートメッセージキューに移動させます。
dataHolderの[[RemotePort]]がnullでない場合、絡め合いを行います。これにより、dataHolderの[[RemotePort]]が元の転送されたポートから解きほぐされます。
メッセージポートのメッセージ送信手順は、sourcePort、targetPort、message、およびoptionsが与えられた場合に次のように進められます:
transferをoptions["transfer"]とします。
もしtransferが含まれている場合、sourcePortがあれば、"DataCloneError"DOMExceptionをスローします。
doomedをfalseとします。
もしtargetPortがnullでなく、かつtransferが含まれている場合、doomedをtrueに設定し、開発者コンソールにターゲットポートが自分自身に投稿されたことをオプションで報告し、通信チャンネルが失われたことを通知します。
serializeWithTransferResultをStructuredSerializeWithTransfer(message, transfer)とし、例外が発生した場合は再スローします。
もしtargetPortがnullであるか、またはdoomedがtrueである場合は、終了します。
targetPortのポートメッセージキューに次の手順を実行するタスクを追加します:
finalTargetPortをMessagePortとし、そのタスクが現在どのポートメッセージキューにあるかを確認します。
これは、targetPort自体が転送され、そのすべてのタスクがそれに伴って移動した場合、targetPortとは異なる場合があります。
targetRealmをfinalTargetPortの関連領域とします。
deserializeRecordをStructuredDeserializeWithTransfer(serializeWithTransferResult, targetRealm)とします。
これで例外が発生した場合、それをキャッチし、イベントを発生させるmessageerrorと呼ばれるイベントをfinalTargetPortで発生させ、MessageEventを使用して処理し、終了します。
messageCloneをdeserializeRecordの[[Deserialized]]とします。
newPortsをdeserializeRecordの[[TransferredValues]]に含まれるすべてのMessagePortオブジェクトで構成される新しいフローズン配列とし、それらの相対的な順序を維持します。
イベントを発生させるmessageと呼ばれるイベントをfinalTargetPortで発生させ、MessageEventを使用し、data属性をmessageCloneで初期化し、ports属性をnewPortsで初期化します。
postMessage(message, options)メソッドの手順は以下の通りです:
targetPortを、このと絡め合っているポートとし、それ以外の場合はnullとします。
メッセージポートのメッセージ送信手順を実行し、この、targetPort、messageおよびoptionsを提供します。
postMessage(message, transfer)メソッドの手順は以下の通りです:
targetPortを、このと絡め合っているポートとし、それ以外の場合はnullとします。
optionsを「transfer」→
transfer」とします。
メッセージポートのメッセージ送信手順を実行し、この、targetPort、messageおよびoptionsを提供します。
The start()
method steps are to enable this's port
message queue, if it is not
already enabled.
close()メソッドの手順は以下の通りです:
thisの[[Detached]]内部スロットの値をtrueに設定します。
以下はイベントハンドラー(および対応するイベントハンドラーのイベントタイプ)であり、すべてのMessagePortインターフェイスを実装するオブジェクトがイベントハンドラーIDL属性としてサポートしなければなりません:
| イベントハンドラー | イベントハンドラーのイベントタイプ |
|---|---|
onmessage
すべての現行エンジンでサポートされています。 Firefox41+Safari5+Chrome2+
Opera10.6+Edge79+ Edge (Legacy)12+Internet Explorer10+ Firefox Android?Safari iOS?Chrome Android?WebView Android37+Samsung Internet?Opera Android11.5+ |
message
|
onmessageerror
MessagePort/messageerror_event すべての現行エンジンでサポートされています。 Firefox57+Safari16.4+Chrome60+
Opera?Edge79+ Edge (Legacy)18Internet ExplorerNo Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android47+ |
messageerror
|
onclose |
close
|
初めてMessagePortオブジェクトのonmessageIDL属性が設定されると、そのポートのポートメッセージキューが有効にされ、start()メソッドが呼び出されたかのように動作します。
MessagePort オブジェクト
o がガベージコレクションされた場合、もし o がエンタングルされている場合、ユーザーエージェントは ディセンタングル を実行する必要があります。
o を。
MessagePort オブジェクト
o がエンタングルされていて、メッセージ または
メッセージエラー
イベントリスナーが登録されている場合、ユーザーエージェントは o のエンタングルされた
MessagePort
オブジェクトが o に強い参照を持っているかのように振る舞わなければなりません。
さらに、MessagePort オブジェクトは、
そのオブジェクトに対してディスパッチされる予定の タスク
によって参照されるイベントが存在する間、またはその
MessagePort オブジェクトの
ポートメッセージキュー が
有効であり、空でない間はガベージコレクションされてはなりません。
したがって、メッセージポートは受信され、イベントリスナーが与えられ、忘れられることができ、 そのイベントリスナーがメッセージを受信できる限り、チャネルは維持されます。
もちろん、これがチャネルの両側で発生した場合、両方のポートはガベージコレクションされる可能性があり、 生きたコードから到達できないにもかかわらず、互いに強い参照を持っているためです。 しかし、メッセージポートに保留中のメッセージがある場合、ガベージコレクションされることはありません。
著者は、リソースが再収集されるように、MessagePort
オブジェクトを明示的に閉じてディセンタングルすることを強く推奨されます。
多くの MessagePort オブジェクトを作成し、
閉じずに破棄することは、特に MessagePort
に関しては、クロスプロセスの調整を伴うガベージコレクションが発生するため、ガベージコレクションが必ずしも迅速に行われないため、一時的なメモリ使用量が高くなる可能性があります。
すべての現在のエンジンでサポートされています。
すべての現在のエンジンでサポートされています。
同じユーザーエージェントで、異なる無関係の 閲覧コンテキスト において 同じユーザーが開いた、単一の オリジン 上のページは、 互いに通知を送信する必要があることがあります。例えば、「こちらでユーザーがログインしましたので、再度資格情報を確認してください」といった通知です。
より複雑なケース、例えば共有状態のロックの管理、サーバーと複数のローカルクライアント間のリソースの同期管理、リモートホストとの
WebSocket
接続の共有などでは、共有ワーカー が
最も適した解決策です。
しかし、共有ワーカーが過剰な負荷となるような単純なケースでは、著者はこのセクションで説明するシンプルなチャネルベースのブロードキャストメカニズムを使用することができます。
[Exposed =(Window ,Worker )]
interface BroadcastChannel : EventTarget {
constructor (DOMString name );
readonly attribute DOMString name ;
undefined postMessage (any message );
undefined close ();
attribute EventHandler onmessage ;
attribute EventHandler onmessageerror ;
};
broadcastChannel = new BroadcastChannel(name)
BroadcastChannel/BroadcastChannel
すべての現在のエンジンでサポートされています。
指定されたチャンネル名に対してメッセージの送受信を行うための新しい BroadcastChannel
オブジェクトを返します。
broadcastChannel.name
すべての現在のエンジンでサポートされています。
チャンネル名(コンストラクタに渡されたもの)を返します。
broadcastChannel.postMessage(message)
すべての現在のエンジンでサポートされています。
指定されたメッセージを、同じチャンネルに設定された他の BroadcastChannel
オブジェクトに送信します。メッセージは、ネストされたオブジェクトや配列など、構造化されたオブジェクトにすることができます。
broadcastChannel.close()
すべての現在のエンジンでサポートされています。
BroadcastChannel
オブジェクトを閉じ、ガベージコレクションにかけることができます。
A BroadcastChannel
オブジェクトは、チャンネル名と閉じられたフラグを持っています。
new BroadcastChannel(name)のコンストラクタ手順は次の通りです:
nameのゲッターステップは、thisのチャンネル名を返します。
BroadcastChannel
オブジェクトは、次の条件を満たすときにメッセージ送信の対象とみなされます:
Window
オブジェクトが、その関連付けられたDocumentが完全にアクティブな場合。
WorkerGlobalScope
オブジェクトが、閉じるフラグがfalseであり、
かつそのworkerがサスペンダブルワーカーでない場合。
postMessage(message)メソッドの手順は次の通りです:
thisがメッセージ送信の対象でない場合、 処理を終了します。
thisの閉じられたフラグがtrueの場合、
"InvalidStateError"
DOMExceptionをスローします。
serializedを、StructuredSerialize(message)で取得します。 例外を再スローします。
sourceOriginをthisの関連設定オブジェクトの オリジンとして設定します。
sourceStorageKeyを、ストレージ目的ではない場合のストレージキーを取得します。 取得するにはthisの関連設定オブジェクトを使用します。
destinationsリストを、次の条件を満たすBroadcastChannel
オブジェクトで作成します:
それらがメッセージ送信の対象である。
それらの関連設定オブジェクトが、 sourceStorageKeyと等しいストレージキーを持つ。
sourceをdestinationsから削除します。
destinationsを、関連エージェント
が同じであるすべてのBroadcastChannel
オブジェクトが作成順で古いものから並ぶように並べ替えます。
(これは完全な順序を定義するものではありません。この制約内で、ユーザーエージェントはリストを実装定義の方法で並べ替えることができます。)
各destinationについて、グローバルタスクをキューに追加 します。 DOM操作タスクソース に基づき、destinationの関連するグローバルオブジェクト に対して、以下のステップを実行します:
もしdestinationの閉じられたフラグがtrueの場合、 これらのステップを中止します。
targetRealmをdestinationの関連するレルム に設定します。
dataをStructuredDeserialize(serialized, targetRealm)で取得します。
これが例外をスローした場合は、例外をキャッチし、イベントを発火し、messageerror
という名前のイベントを、destinationで発火し、
MessageEvent
を使用し、オリジンのシリアル化
に基づいてsourceOriginを初期化します。次に、これらのステップを中止します。
イベントを発火し、message
という名前のイベントをdestinationで発火し、MessageEvent
を使用し、data
属性をdataで初期化し、origin
属性をsourceOriginのシリアル化で初期化します。
BroadcastChannel
オブジェクトが、閉じられたフラグ
がfalseのときにmessage
または
messageerror
イベントのリスナーが登録されている場合、
BroadcastChannel
オブジェクト自体に対する
BroadcastChannel
オブジェクトの関連するグローバルオブジェクト
からの強い参照が存在しなければなりません。
close()メソッドの手順は、thisの閉じられたフラグ
をtrueに設定することです。
作成されたBroadcastChannel
オブジェクトは、不要になったら明示的に閉じることが強く推奨されます。
多数のBroadcastChannel
オブジェクトを作成して、イベントリスナーを残したまま閉じずに放置すると、オブジェクトがイベントリスナーを持っている限り、
(またはそのページやワーカーが閉じられるまで)オブジェクトが生き続けるため、見かけ上のメモリリークを引き起こす可能性があります。
次のものは、イベントハンドラー
(およびそれらに対応するイベントハンドラーイベントタイプ)で、
すべてのBroadcastChannel
インターフェイスを実装するオブジェクトが
イベントハンドラーIDL属性
としてサポートしなければならないものです。
| イベントハンドラー | イベントハンドラーイベントタイプ |
|---|---|
onmessage
BroadcastChannel/message_event すべての現在のエンジンでサポートされています。 Firefox38+Safari15.4+Chrome54+
Opera?Edge79+ Edge (Legacy)?Internet Explorerいいえ Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android? | message
|
onmessageerror
BroadcastChannel/messageerror_event すべての現在のエンジンでサポートされています。 Firefox57+Safari15.4+Chrome60+
Opera?Edge79+ Edge (Legacy)?Internet Explorerいいえ Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android47+ | messageerror
|
例えば、ユーザーが別のタブでログアウトしたときにページが通知を受け取る必要がある場合:
var authChannel = new BroadcastChannel( 'auth' );
authChannel. onmessage = function ( event) {
if ( event. data == 'logout' )
showLogout();
}
function logoutRequested() {
// ユーザーがログアウトを要求したときに呼び出される
doLogout();
showLogout();
authChannel. postMessage( 'logout' );
}
function doLogout() {
// ユーザーを実際にログアウトさせる(例: クッキーのクリア)
// ...
}
function showLogout() {
// ログアウトしたことを示すUIの更新
// ...
}
すべての現在のエンジンでサポートされています。
このセクションは規範ではありません。
この仕様は、ユーザーインターフェイススクリプトとは独立してバックグラウンドでスクリプトを実行するための API を定義します。
これにより、クリックやその他のユーザー操作に応答するスクリプトによって中断されることなく、長時間実行されるスクリプトを実行でき、ページを応答性を維持しながら長時間実行できるようにします。
ここで述べるバックグラウンドスクリプト(ワーカーと呼ばれます)は比較的重いものであり、大量に使用することは意図されていません。たとえば、4 メガピクセルの画像の各ピクセルに 1 つのワーカーを起動することは不適切です。以下の例では、ワーカーの適切な使用例を示します。
一般的に、ワーカーは長期間の存続が期待され、起動時のパフォーマンスコストが高く、インスタンスごとのメモリコストも高いです。
このセクションは規範ではありません。
ワーカーを使用するさまざまな用途があります。以下のサブセクションでは、これらの使用例をいくつか紹介します。
このセクションは規範ではありません。
ワーカーの最も簡単な使用法は、ユーザーインターフェイスを中断することなく計算負荷の高いタスクを実行することです。
この例では、メインドキュメントがワーカーを生成して素数を(単純に)計算し、見つかったばかりの素数を逐次的に表示します。
メインページは次のとおりです。
<!DOCTYPE HTML>
< html lang = "en" >
< head >
< meta charset = "utf-8" >
< title > Worker example: One-core computation</ title >
</ head >
< body >
< p > The highest prime number discovered so far is: < output id = "result" ></ output ></ p >
< script >
var worker = new Worker( 'worker.js' );
worker. onmessage = function ( event) {
document. getElementById( 'result' ). textContent = event. data;
};
</ script >
</ body >
</ html >
Worker()
コンストラクターの呼び出しは、ワーカーを作成し、そのワーカーを表す Worker
オブジェクトを返します。このオブジェクトはワーカーと通信するために使用されます。そのオブジェクトの onmessage
イベントハンドラーは、ワーカーからのメッセージを受け取るコードを許可します。
ワーカー自体は次のようになります:
var n = 1 ;
search: while ( true ) {
n += 1 ;
for ( var i = 2 ; i <= Math. sqrt( n); i += 1 )
if ( n % i == 0 ) continue search; // 素数を発見しました!
postMessage( n);
}
このコードの大部分は、素数を検索する最適化されていないコードです。素数が見つかったときに、postMessage()
メソッドを使用してページにメッセージを送信します。
このセクションは規範ではありません。
これまでの例では、クラシックスクリプトを実行するワーカーを示してきました。ワーカーは、代わりにモジュールスクリプトを使用してインスタンス化することもでき、通常の利点を備えています。たとえば、他のモジュールをインポートするための
JavaScript import ステートメントを使用できること、デフォルトで厳格モードであること、トップレベルの宣言がワーカーのグローバルスコープを汚染しないことなどです。
import ステートメントが使用可能であるため、importScripts()
メソッドは、モジュールワーカー内で自動的に失敗します。
この例では、メインドキュメントがワーカーを使用してオフメインスレッドの画像操作を行います。使用するフィルタは別のモジュールからインポートされています。
メインページは次のとおりです:
<!DOCTYPE html>
< html lang = "en" >
< meta charset = "utf-8" >
< title > Worker example: image decoding</ title >
< p >
< label >
画像の URL を入力してデコード
< input type = "url" id = "image-url" list = "image-list" >
< datalist id = "image-list" >
< option value = "https://html.spec.whatwg.org/images/drawImage.png" >
< option value = "https://html.spec.whatwg.org/images/robots.jpeg" >
< option value = "https://html.spec.whatwg.org/images/arcTo2.png" >
</ datalist >
</ label >
</ p >
< p >
< label >
適用するフィルタを選択
< select id = "filter" >
< option value = "none" > なし</ option >
< option value = "grayscale" > グレースケール</ option >
< option value = "brighten" > 20% 明るく</ option >
</ select >
</ label >
</ p >
< div id = "output" ></ div >
< script type = "module" >
const worker = new Worker( "worker.js" , { type: "module" });
worker. onmessage = receiveFromWorker;
const url = document. querySelector( "#image-url" );
const filter = document. querySelector( "#filter" );
const output = document. querySelector( "#output" );
url. oninput = updateImage;
filter. oninput = sendToWorker;
let imageData, context;
function updateImage() {
const img = new Image();
img. src = url. value;
img. onload = () => {
const canvas = document. createElement( "canvas" );
canvas. width = img. width;
canvas. height = img. height;
context = canvas. getContext( "2d" );
context. drawImage( img, 0 , 0 );
imageData = context. getImageData( 0 , 0 , canvas. width, canvas. height);
sendToWorker();
output. replaceChildren( canvas);
};
}
function sendToWorker() {
worker. postMessage({ imageData, filter: filter. value });
}
function receiveFromWorker( e) {
context. putImageData( e. data, 0 , 0 );
}
</ script >
次に、ワーカーファイルは次のようになります:
import * as filters from "./filters.js" ;
self. onmessage = e => {
const { imageData, filter } = e. data;
filters[ filter]( imageData);
self. postMessage( imageData, [ imageData. data. buffer]);
};
これがファイル filters.js からインポートされています:
export function none() {}
export function grayscale({ data: d }) {
for ( let i = 0 ; i < d. length; i += 4 ) {
const [ r, g, b] = [ d[ i], d[ i + 1 ], d[ i + 2 ]];
// CIE ルミナンス (RGB に対して)
// 人間の目は赤と青を見るのが苦手なので、それらを軽視します。
d[ i] = d[ i + 1 ] = d[ i + 2 ] = 0.2126 * r + 0.7152 * g + 0.0722 * b;
}
すべての現在のエンジンでサポートされています。
このセクションは規範ではありません。
このセクションでは、共有ワーカーの「Hello World」例を紹介します。共有ワーカーは、複数の接続を持つことができるため、専用ワーカーとは異なる API を使用します。
この最初の例では、ワーカーに接続する方法と、ワーカーが接続時にページにメッセージを送信する方法を示しています。受信したメッセージはログに表示されます。
以下は HTML ページです:
<!DOCTYPE HTML>
< html lang = "en" >
< meta charset = "utf-8" >
< title > 共有ワーカー: デモ 1</ title >
< pre id = "log" > ログ:</ pre >
< script >
var worker = new SharedWorker( 'test.js' );
var log = document. getElementById( 'log' );
worker. port. onmessage = function ( e) { // 注: worker.onmessage ではありません!
log. textContent += '\n' + e. data;
}
</ script >
以下は JavaScript ワーカーです:
onconnect = function ( e) {
var port = e. ports[ 0 ];
port. postMessage( 'Hello World!' );
}
この2番目の例では、最初の例を拡張し、2つの点を変更しています。まず、メッセージがイベントハンドラー IDL
属性ではなく、addEventListener()
を使用して受信されるようになります。そして2番目に、ワーカーにメッセージが送信され、ワーカーがそれに応じてもう一度メッセージを送信します。受信したメッセージは再びログに表示されます。
以下は HTML ページです:
<!DOCTYPE HTML>
< html lang = "en" >
< meta charset = "utf-8" >
< title > 共有ワーカー: デモ 2</ title >
< pre id = "log" > ログ:</ pre >
< script >
var worker = new SharedWorker( 'test.js' );
var log = document. getElementById( 'log' );
worker. port. addEventListener( 'message' , function ( e) {
log. textContent += '\n' + e. data;
}, false );
worker. port. start(); // 注: addEventListener を使用する場合にはこれが必要です
worker. port. postMessage( 'ping' );
</ script >
以下は JavaScript ワーカーです:
onconnect = function ( e) {
var port = e. ports[ 0 ];
port. postMessage( 'Hello World!' );
port. onmessage = function ( e) {
port. postMessage( 'pong' ); // e.ports[0].postMessage ではありません!
// e.target.postMessage('pong') でも機能します
}
}
最後に、例をさらに拡張して、2つのページが同じワーカーに接続する方法を示します。この場合、2 番目のページは最初のページの iframe にすぎませんが、同じ原理が別の トップレベル トラバーサブル にある完全に別のページにも適用されます。
以下は外部 HTML ページです:
<!DOCTYPE HTML>
< html lang = "en" >
< meta charset = "utf-8" >
< title > 共有ワーカー: デモ 3</ title >
< pre id = "log" > ログ:</ pre >
< script >
var worker = new SharedWorker( 'test.js' );
var log = document. getElementById( 'log' );
worker. port. addEventListener( 'message' , function ( e) {
log. textContent += '\n' + e. data;
}, false );
worker. port. start();
worker. port. postMessage( 'ping' );
</ script >
< iframe src = "inner.html" ></ iframe >
以下は内部 HTML ページです:
<!DOCTYPE HTML>
< html lang = "en" >
< meta charset = "utf-8" >
< title > 共有ワーカー: デモ 3 内部フレーム</ title >
< pre id = log > 内部ログ:</ pre >
< script >
var worker = new SharedWorker( 'test.js' );
var log = document. getElementById( 'log' );
worker. port. onmessage = function ( e) {
log. textContent += '\n' + e. data;
}
</ script >
以下は JavaScript ワーカーです:
var count = 0 ;
onconnect = function ( e) {
count += 1 ;
var port = e. ports[ 0 ];
port. postMessage( 'Hello World! あなたは接続 #' + count);
port. onmessage = function ( e) {
port. postMessage( 'pong' );
}
}
このセクションは規範的ではありません。
この例では、同じ地図を表示している複数のウィンドウ(ビューアー)を開くことができます。すべてのウィンドウは同じ地図情報を共有しており、単一のワーカーがすべてのビューアーを調整します。各ビューアーは独立して移動できますが、地図上にデータを設定すると、すべてのビューアーが更新されます。
メインページは特に面白くなく、ビューアーを開く手段を提供するだけです:
<!DOCTYPE HTML>
< html lang = "en" >
< head >
< meta charset = "utf-8" >
< title > Workers example: Multiviewer</ title >
< script >
function openViewer() {
window. open( 'viewer.html' );
}
</ script >
</ head >
< body >
< p >< button type = button onclick = "openViewer()" > Open a new
viewer</ button ></ p >
< p > Each viewer opens in a new window. You can have as many viewers
as you like, they all view the same data.</ p >
</ body >
</ html >
ビューアーの方がもっと複雑です:
<!DOCTYPE HTML>
< html lang = "en" >
< head >
< meta charset = "utf-8" >
< title > Workers example: Multiviewer viewer</ title >
< script >
var worker = new SharedWorker( 'worker.js' , 'core' );
// CONFIGURATION
function configure( event) {
if ( event. data. substr( 0 , 4 ) != 'cfg ' ) return ;
var name = event. data. substr( 4 ). split( ' ' , 1 )[ 0 ];
// update display to mention our name is name
document. getElementsByTagName( 'h1' )[ 0 ]. textContent += ' ' + name;
// no longer need this listener
worker. port. removeEventListener( 'message' , configure, false );
}
worker. port. addEventListener( 'message' , configure, false );
// MAP
function paintMap( event) {
if ( event. data. substr( 0 , 4 ) != 'map ' ) return ;
var data = event. data. substr( 4 ). split( ',' );
// display tiles data[0] .. data[8]
var canvas = document. getElementById( 'map' );
var context = canvas. getContext( '2d' );
for ( var y = 0 ; y < 3 ; y += 1 ) {
for ( var x = 0 ; x < 3 ; x += 1 ) {
var tile = data[ y * 3 + x];
if ( tile == '0' )
context. fillStyle = 'green' ;
else
context. fillStyle = 'maroon' ;
context. fillRect( x * 50 , y * 50 , 50 , 50 );
}
}
}
worker. port. addEventListener( 'message' , paintMap, false );
// PUBLIC CHAT
function updatePublicChat( event) {
if ( event. data. substr( 0 , 4 ) != 'txt ' ) return ;
var name = event. data. substr( 4 ). split( ' ' , 1 )[ 0 ];
var message = event. data. substr( 4 + name. length + 1 );
// display "<name> message" in public chat
var public = document. getElementById( 'public' );
var p = document. createElement( 'p' );
var n = document. createElement( 'button' );
n. textContent = '<' + name + '> ' ;
n. onclick = function () { worker. port. postMessage( 'msg ' + name); };
p. appendChild( n);
var m = document. createElement( 'span' );
m. textContent = message;
p. appendChild( m);
public. appendChild( p);
}
worker. port. addEventListener( 'message' , updatePublicChat, false );
// PRIVATE CHAT
function startPrivateChat( event) {
if ( event. data. substr( 0 , 4 ) != 'msg ' ) return ;
var name = event. data. substr( 4 ). split( ' ' , 1 )[ 0 ];
var port = event. ports[ 0 ];
// display a private chat UI
var ul = document. getElementById( 'private' );
var li = document. createElement( 'li' );
var h3 = document. createElement( 'h3' );
h3. textContent = 'Private chat with ' + name;
li. appendChild( h3);
var div = document. createElement( 'div' );
var addMessage = function ( name, message) {
var p = document. createElement( 'p' );
var n = document. createElement( 'strong' );
n. textContent = '<' + name + '> ' ;
p. appendChild( n);
var t = document. createElement( 'span' );
t. textContent = message;
p. appendChild( t);
div. appendChild( p);
};
port. onmessage = function ( event) {
addMessage( name, event. data);
};
li. appendChild( div);
var form = document. createElement( 'form' );
var p = document. createElement( 'p' );
var input = document. createElement( 'input' );
input. size = 50 ;
p. appendChild( input);
p. appendChild( document. createTextNode( ' ' ));
var button = document. createElement( 'button' );
button. textContent = 'Post' ;
p. appendChild( button);
form. onsubmit = function () {
port. postMessage( input. value);
addMessage( 'me' , input. value);
input. value = '' ;
return false ;
};
form. appendChild( p);
li. appendChild( form);
ul. appendChild( li);
}
worker. port. addEventListener( 'message' , startPrivateChat, false );
worker. port. start();
</ script >
</ head >
< body >
< h1 > Viewer</ h1 >
< h2 > Map</ h2 >
< p >< canvas id = "map" height = 150 width = 150 ></ canvas ></ p >
< p >
< button type = button onclick = "worker.port.postMessage('mov left')" > Left</ button >
< button type = button onclick = "worker.port.postMessage('mov up')" > Up</ button >
< button type = button onclick = "worker.port.postMessage('mov down')" > Down</ button >
< button type = button onclick = "worker.port.postMessage('mov right')" > Right</ button >
< button type = button onclick = "worker.port.postMessage('set 0')" > Set 0</ button >
< button type = button onclick = "worker.port.postMessage('set 1')" > Set 1</ button >
</ p >
< h2 > Public Chat</ h2 >
< div id = "public" ></ div >
< form onsubmit = "worker.port.postMessage('txt ' + message.value); message.value = ''; return false;" >
< p >
< input type = "text" name = "message" size = "50" >
< button > Post</ button >
</ p >
</ form >
< h2 > Private Chat</ h2 >
< ul id = "private" ></ ul >
</ body >
</ html >
ビューアーの記述方法について、いくつか重要な点があります。
複数のリスナー。単一のメッセージ処理関数の代わりに、ここでは複数のイベントリスナーをアタッチしており、それぞれがメッセージに関連しているかを迅速に確認します。この例では大きな違いはありませんが、複数の著者が一つのポートを使ってワーカーと通信し、協力しようとする場合、それぞれのコードが独立して動作し、すべての変更を一つのイベント処理関数にまとめる必要がなくなります。
この方法でイベントリスナーを登録することで、特定のリスナーが不要になったときに、configure()メソッドで行われているように、それらを解除することができます。
最後に、ワーカーについて:
var nextName = 0 ;
function getNextName() {
// this could use more friendly names
// but for now just return a number
return nextName++ ;
}
var map = [
[ 0 , 0 , 0 , 0 , 0 , 0 , 0 ],
[ 1 , 1 , 0 , 1 , 0 , 1 , 1 ],
[ 0 , 1 , 0 , 1 , 0 , 0 , 0 ],
[ 0 , 1 , 0 , 1 , 0 , 1 , 1 ],
[ 0 , 0 , 0 , 1 , 0 , 0 , 0 ],
[ 1 , 0 , 0 , 1 , 1 , 1 , 1 ],
[ 1 , 1 , 0 , 1 , 1 , 0 , 1 ],
];
function wrapX( x) {
if ( x < 0 ) return wrapX( x + map[ 0 ]. length);
if ( x >= map[ 0 ]. length) return wrapX( x - map[ 0 ]. length);
return x;
}
function wrapY( y) {
if ( y < 0 ) return wrapY( y + map. length);
if ( y >= map[ 0 ]. length) return wrapY( y - map. length);
return y;
}
function wrap( val, min, max) {
if ( val < min)
return val + ( max- min) + 1 ;
if ( val > max)
return val - ( max- min) - 1 ;
return val;
}
function sendMapData( viewer) {
var data = '' ;
for ( var y = viewer. y- 1 ; y <= viewer. y+ 1 ; y += 1 ) {
for ( var x = viewer. x- 1 ; x <= viewer. x+ 1 ; x += 1 ) {
if ( data != '' )
data += ',' ;
data += map[ wrap( y, 0 , map[ 0 ]. length- 1 )][ wrap( x, 0 , map. length- 1 )];
}
}
viewer. port. postMessage( 'map ' + data);
}
var viewers = {};
onconnect = function ( event) {
var name = getNextName();
event. ports[ 0 ]. _data = { port: event. ports[ 0 ], name: name, x: 0 , y: 0 , };
viewers[ name] = event. ports[ 0 ]. _data;
event. ports[ 0 ]. postMessage( 'cfg ' + name);
event. ports[ 0 ]. onmessage = getMessage;
sendMapData( event. ports[ 0 ]. _data);
};
function getMessage( event) {
switch ( event. data. substr( 0 , 4 )) {
case 'mov ' :
var direction = event. data. substr( 4 );
var dx = 0 ;
var dy = 0 ;
switch ( direction) {
case 'up' : dy = - 1 ; break ;
case 'down' : dy = 1 ; break ;
case 'left' : dx = - 1 ; break ;
case 'right' : dx = 1 ; break ;
}
event. target. _data. x = wrapX( event. target. _data. x + dx);
event. target. _data. y = wrapY( event. target. _data. y + dy);
sendMapData( event. target. _data);
break ;
case 'set ' :
var value = event. data. substr( 4 );
map[ event. target. _data. y][ event. target. _data. x] = value;
for ( var viewer in viewers)
sendMapData( viewers[ viewer]);
break ;
case 'txt ' :
var name = event. target. _data. name;
var message = event. data. substr( 4 );
for ( var viewer in viewers)
viewers[ viewer]. port. postMessage( 'txt ' + name + ' ' + message);
break ;
case 'msg ' :
var party1 = event. target. _data;
var party2 = viewers[ event. data. substr( 4 ). split( ' ' , 1 )[ 0 ]];
if ( party2) {
var channel = new MessageChannel();
party1. port. postMessage( 'msg ' + party2. name, [ channel. port1]);
party2. port. postMessage( 'msg ' + party1. name, [ channel. port2]);
}
break ;
}
}
複数ページへの接続。このスクリプトは、onconnect
イベントリスナーを使用して、複数の接続をリッスンします。
ダイレクトチャネル。ワーカーがあるビューアーから他のビューアーを指定する「msg」メッセージを受信すると、2つのビューアー間に直接接続を設定し、ワーカーがすべてのメッセージをプロキシする必要がなくなります。
このセクションは規範的ではありません。
マルチコアCPUが普及している現在、より良いパフォーマンスを得る一つの方法は、計算コストの高いタスクを複数のワーカーに分割することです。この例では、1から10,000,000までの各数に対して行われる計算コストの高いタスクを、10個のサブワーカーに分散させています。
メインページは次のとおりで、結果を報告するだけです:
<!DOCTYPE HTML>
< html lang = "en" >
< head >
< meta charset = "utf-8" >
< title > Worker example: Multicore computation</ title >
</ head >
< body >
< p > Result: < output id = "result" ></ output ></ p >
< script >
var worker = new Worker( 'worker.js' );
worker. onmessage = function ( event) {
document. getElementById( 'result' ). textContent = event. data;
};
</ script >
</ body >
</ html >
ワーカー自体は次のとおりです:
// settings
var num_workers = 10 ;
var items_per_worker = 1000000 ;
// start the workers
var result = 0 ;
var pending_workers = num_workers;
for ( var i = 0 ; i < num_workers; i += 1 ) {
var worker = new Worker( 'core.js' );
worker. postMessage( i * items_per_worker);
worker. postMessage(( i+ 1 ) * items_per_worker);
worker. onmessage = storeResult;
}
// handle the results
function storeResult( event) {
result += 1 * event. data;
pending_workers -= 1 ;
if ( pending_workers <= 0 )
postMessage( result); // finished!
}
これはサブワーカーを開始するためのループと、すべてのサブワーカーが応答するのを待つハンドラーで構成されています。
サブワーカーは次のように実装されています:
var start;
onmessage = getStart;
function getStart( event) {
start = 1 * event. data;
onmessage = getEnd;
}
var end;
function getEnd( event) {
end = 1 * event. data;
onmessage = null ;
work();
}
function work() {
var result = 0 ;
for ( var i = start; i < end; i += 1 ) {
// perform some complex calculation here
result += 1 ;
}
postMessage( result);
close();
}
彼らは2つのイベントで2つの数字を受け取り、その指定された範囲の数字に対して計算を行い、結果を親に報告します。
このセクションは規範的ではありません。
暗号ライブラリが提供され、次の3つのタスクを実行できると仮定します:
ライブラリ自体は次のとおりです:
function handleMessage( e) {
if ( e. data == "genkeys" )
genkeys( e. ports[ 0 ]);
else if ( e. data == "encrypt" )
encrypt( e. ports[ 0 ]);
else if ( e. data == "decrypt" )
decrypt( e. ports[ 0 ]);
}
function genkeys( p) {
var keys = _generateKeyPair();
p. postMessage( keys[ 0 ]);
p. postMessage( keys[ 1 ]);
}
function encrypt( p) {
var key, state = 0 ;
p. onmessage = function ( e) {
if ( state == 0 ) {
key = e. data;
state = 1 ;
} else {
p. postMessage( _encrypt( key, e. data));
}
};
}
function decrypt( p) {
var key, state = 0 ;
p. onmessage = function ( e) {
if ( state == 0 ) {
key = e. data;
state = 1 ;
} else {
p. postMessage( _decrypt( key, e. data));
}
};
}
// support being used as a shared worker as well as a dedicated worker
if ( 'onmessage' in this ) // dedicated worker
onmessage = handleMessage;
else // shared worker
onconnect = function ( e) { e. port. onmessage = handleMessage; }
// the "crypto" functions:
function _generateKeyPair() {
return [ Math. random(), Math. random()];
}
function _encrypt( k, s) {
return 'encrypted-' + k + ' ' + s;
}
function _decrypt( k, s) {
return s. substr( s. indexOf( ' ' ) + 1 );
}
ここでの暗号関数は単なるスタブであり、実際の暗号化は行いません。
このライブラリは次のように使用できます:
<!DOCTYPE HTML>
< html lang = "en" >
< head >
< meta charset = "utf-8" >
< title > Worker example: Crypto library</ title >
< script >
const cryptoLib = new Worker( 'libcrypto-v1.js' ); // or could use 'libcrypto-v2.js'
function startConversation( source, message) {
const messageChannel = new MessageChannel();
source. postMessage( message, [ messageChannel. port2]);
return messageChannel. port1;
}
function getKeys() {
let state = 0 ;
startConversation( cryptoLib, "genkeys" ). onmessage = function ( e) {
if ( state === 0 )
document. getElementById( 'public' ). value = e. data;
else if ( state === 1 )
document. getElementById( 'private' ). value = e. data;
state += 1 ;
};
}
function enc() {
const port = startConversation( cryptoLib, "encrypt" );
port. postMessage( document. getElementById( 'public' ). value);
port. postMessage( document. getElementById( 'input' ). value);
port. onmessage = function ( e) {
document. getElementById( 'input' ). value = e. data;
port. close();
};
}
function dec() {
const port = startConversation( cryptoLib, "decrypt" );
port. postMessage( document. getElementById( 'private' ). value);
port. postMessage( document. getElementById( 'input' ). value);
port. onmessage = function ( e) {
document. getElementById( 'input' ). value = e. data;
port. close();
};
}
</ script >
< style >
textarea { display : block ; }
</ style >
</ head >
< body onload = "getKeys()" >
< fieldset >
< legend > Keys</ legend >
< p >< label > Public Key: < textarea id = "public" ></ textarea ></ label ></ p >
< p >< label > Private Key: < textarea id = "private" ></ textarea ></ label ></ p >
</ fieldset >
< p >< label > Input: < textarea id = "input" ></ textarea ></ label ></ p >
< p >< button onclick = "enc()" > Encrypt</ button > < button onclick = "dec()" > Decrypt</ button ></ p >
</ body >
</ html >
ただし、後のバージョンのAPIでは、すべての暗号作業をサブワーカーにオフロードすることを検討するかもしれません。次のようにして実現できます:
function handleMessage( e) {
if ( e. data == "genkeys" )
genkeys( e. ports[ 0 ]);
else if ( e. data == "encrypt" )
encrypt( e. ports[ 0 ]);
else if ( e. data == "decrypt" )
decrypt( e. ports[ 0 ]);
}
function genkeys( p) {
var generator = new Worker( 'libcrypto-v2-generator.js' );
generator. postMessage( '' , [ p]);
}
function encrypt( p) {
p. onmessage = function ( e) {
var key = e. data;
var encryptor = new Worker( 'libcrypto-v2-encryptor.js' );
encryptor. postMessage( key, [ p]);
};
}
function encrypt( p) {
p. onmessage = function ( e) {
var key = e. data;
var decryptor = new Worker( 'libcrypto-v2-decryptor.js' );
decryptor. postMessage( key, [ p]);
};
}
// support being used as a shared worker as well as a dedicated worker
if ( 'onmessage' in this ) // dedicated worker
onmessage = handleMessage;
else // shared worker
onconnect = function ( e) { e. ports[ 0 ]. onmessage = handleMessage };
小さなサブワーカーは次のようになります。
鍵ペアの生成に関しては:
onmessage = function ( e) {
var k = _generateKeyPair();
e. ports[ 0 ]. postMessage( k[ 0 ]);
e. ports[ 0 ]. postMessage( k[ 1 ]);
close();
}
function _generateKeyPair() {
return [ Math. random(), Math. random()];
}
暗号化の場合:
onmessage = function ( e) {
var key = e. data;
e. ports[ 0 ]. onmessage = function ( e) {
var s = e. data;
postMessage( _encrypt( key, s));
}
}
function _encrypt( k, s) {
return 'encrypted-' + k + ' ' + s;
}
復号化の場合:
onmessage = function ( e) {
var key = e. data;
e. ports[ 0 ]. onmessage = function ( e) {
var s = e. data;
postMessage( _decrypt( key, s));
}
}
function _decrypt( k, s) {
return s. substr( s. indexOf( ' ' ) + 1 );
}
APIのユーザーが、この処理が行われていることを知る必要がないことに注意してください。APIは変更されていません。ライブラリはサブワーカーに委任することができますが、メッセージチャンネルを使用してデータを受け取っているにもかかわらず、APIを変更することなく動作します。
このセクションは規範的ではありません。
ワーカーを作成するには、JavaScriptファイルへのURLが必要です。Worker()コンストラクタが
そのファイルのURLを唯一の引数として呼び出され、ワーカーが作成されて返されます:
var worker = new Worker( 'helper.js' );
ワーカースクリプトをデフォルトのクラシック スクリプトではなくモジュールスクリプトとして解釈させたい場合は、わずかに異なるシグネチャを使用する必要があります:
var worker = new Worker( 'helper.mjs' , { type: "module" });
このセクションは規範的ではありません。
専用ワーカーは背後でMessagePortオブジェクトを使用しており、そのため、構造化データの送信、バイナリデータの転送、他のポートの転送など、すべての同じ機能をサポートします。
専用ワーカーからメッセージを受信するには、onmessage
イベントハンドラーIDL属性をWorkerオブジェクトに使用します:
worker. onmessage = function ( event) { ... };
addEventListener()メソッドも使用できます。
専用ワーカーで使用される暗黙のMessagePortは、作成時に暗黙的にポートメッセージキューが有効化されているため、MessagePortインターフェースのstart()メソッドに相当するものは、Workerインターフェースには存在しません。
ワーカーにデータを送信するには、postMessage()メソッドを使用します。この通信チャネルを介して構造化データを送信できます。ArrayBufferオブジェクトを効率的に送信するためには、2番目の引数に配列としてリストします。
worker. postMessage({
operation: 'find-edges' ,
input: buffer, // an ArrayBuffer object
threshold: 0.6 ,
}, [ buffer]);
ワーカー内でメッセージを受信するには、再びonmessage
イベントハンドラーIDL属性が使用されます。
onmessage = function ( event) { ... };
再びaddEventListener()メソッドも使用できます。
いずれの場合も、データはイベントオブジェクトのdata属性に提供されます。
メッセージを返信するには、再びpostMessage()を使用します。同様に構造化データをサポートしています。
postMessage( event. data. input, [ event. data. input]); // バッファを転送
すべての現在のエンジンでサポートされています。
このセクションは規範的ではありません。
共有ワーカーは、作成に使用されるスクリプトのURL、およびオプションで明示的な名前によって識別されます。この名前を使用すると、特定の共有ワーカーの複数のインスタンスを開始することができます。
共有ワーカーはオリジンによってスコープされます。同じ名前を使用する2つの異なるサイトは衝突しません。ただし、同じサイトの別のページが異なるスクリプトURLで同じ共有ワーカー名を使用しようとすると、失敗します。
共有ワーカーの作成は、SharedWorker()コンストラクタを使用して行われます。このコンストラクタは、最初の引数として使用するスクリプトのURL、および任意でワーカーの名前を引数として受け取ります。
var worker = new SharedWorker( 'service.js' );
共有ワーカーとの通信は、明示的なMessagePortオブジェクトを使用して行われます。SharedWorker()コンストラクタによって返されるオブジェクトは、そのport属性にポートへの参照を保持しています。
worker. port. onmessage = function ( event) { ... };
worker. port. postMessage( 'some message' );
worker. port. postMessage({ foo: 'structured' , bar: [ 'data' , 'also' , 'possible' ]});
共有ワーカー内では、新しいクライアントが接続されるとconnectイベントによって通知されます。新しいクライアントのポートは、イベントオブジェクトのsource属性によって提供されます。
onconnect = function ( event) {
var newPort = event. source;
// リスナーを設定する
newPort. onmessage = function ( event) { ... };
// ポートにメッセージを返す
newPort. postMessage( 'ready!' ); // もちろん構造化データも送信できます
};
この規格は、専用ワーカーと共有ワーカーの2種類のワーカーを定義しています。専用ワーカーは、作成されるとその作成者にリンクされますが、メッセージポートを使用して専用ワーカーから他の複数のブラウジングコンテキストやワーカーと通信することができます。一方、共有ワーカーは名前が付けられ、作成されると同じオリジン内で動作する任意のスクリプトがそのワーカーへの参照を取得し、通信することができます。Service Workersは、第三の種類を定義します。[SW]
グローバルスコープは、ワーカーの「内部」です。
WorkerGlobalScope 共通
インターフェースすべての現在のエンジンでサポートされています。
[Exposed =Worker ]
interface WorkerGlobalScope : EventTarget {
readonly attribute WorkerGlobalScope self ;
readonly attribute WorkerLocation location ;
readonly attribute WorkerNavigator navigator ;
undefined importScripts ((TrustedScriptURL or USVString )... urls );
attribute OnErrorEventHandler onerror ;
attribute EventHandler onlanguagechange ;
attribute EventHandler onoffline ;
attribute EventHandler ononline ;
attribute EventHandler onrejectionhandled ;
attribute EventHandler onunhandledrejection ;
};
WorkerGlobalScope
は、DedicatedWorkerGlobalScope、
SharedWorkerGlobalScope、
およびServiceWorkerGlobalScopeを含む特定のタイプのワーカーグローバルスコープオブジェクトのベースクラスとして機能します。
WorkerGlobalScope
オブジェクトには、関連付けられた オーナーセット(Document および WorkerGlobalScope
オブジェクトの セット)があります。これは、ワーカーが作成または取得されたときに初期化され、空である状態から開始します。
これは単一のオーナーではなく、SharedWorkerGlobalScope
オブジェクトを収容するためのセットです。
WorkerGlobalScope
オブジェクトには、関連付けられた タイプ("classic" または "module")があります。これは作成時に設定されます。
WorkerGlobalScope
オブジェクトには、関連付けられた URL(null または URL)があります。これは最初は null です。
WorkerGlobalScope
オブジェクトには、関連付けられた名前(文字列)があります。これは作成時に設定されます。
名前は、WorkerGlobalScope
の各サブクラスで異なる意味を持つことがあります。
DedicatedWorkerGlobalScope
インスタンスでは、これは主にデバッグの目的で使用される開発者が提供する名前です。SharedWorkerGlobalScope
インスタンスでは、SharedWorker()
コンストラクタを介して共通の共有ワーカーへの参照を取得することができます。
ServiceWorkerGlobalScope
オブジェクトの場合、この概念は意味を持たず(そのため、JavaScript APIではまったく公開されていません)。
WorkerGlobalScope
オブジェクトには、関連付けられたポリシーコンテナ(ポリシーコンテナ)があります。これは最初は新しいポリシーコンテナです。
WorkerGlobalScope
オブジェクトには、関連付けられた埋め込みポリシー(埋め込みポリシー)があります。
WorkerGlobalScope
オブジェクトには、関連付けられたモジュールマップがあります。これはモジュールマップであり、最初は空です。
WorkerGlobalScope
オブジェクトには、関連付けられたクロスオリジンアイソレート機能があります。これは最初はfalseです。
workerGlobal.self
すべての現在のエンジンでサポートされています。
workerGlobal.location
すべての現在のエンジンでサポートされています。
WorkerLocation
オブジェクトを返します。
workerGlobal.navigator
すべての現在のエンジンでサポートされています。
WorkerNavigator
オブジェクトを返します。
workerGlobal.importScripts(...urls)
WorkerGlobalScope/importScripts
すべての現在のエンジンでサポートされています。
self属性は、WorkerGlobalScope
オブジェクト自体を返さなければなりません。
location属性は、関連付けられたWorkerGlobalScope
オブジェクトのWorkerLocation
オブジェクトを返さなければなりません。
WorkerLocation
オブジェクトはWorkerGlobalScope
オブジェクトの後に作成されますが、スクリプトからは観察できないため、これは問題ありません。
以下は、WorkerGlobalScope
インターフェイスを実装するオブジェクトがイベントハンドラーIDL属性としてサポートしなければならない
イベントハンドラー(およびそれに対応する
イベントハンドラーイベントタイプ)です。
| イベントハンドラー | イベントハンドラーイベントタイプ |
|---|---|
onerror
すべての現在のエンジンでサポートされています。 Firefox3.5+Safari4+Chrome4+
Opera11.5+Edge79+ Edge (Legacy)12+Internet Explorer10+ Firefox Android?Safari iOS5+Chrome Android?WebView Android?Samsung Internet?Opera Android? | error
|
onlanguagechange
WorkerGlobalScope/languagechange_event すべての現在のエンジンでサポートされています。 Firefox74+Safari4+Chrome4+
Opera11.5+Edge79+ Edge (Legacy)?Internet ExplorerNo Firefox Android?Safari iOS5+Chrome Android?WebView Android37+Samsung Internet?Opera Android? | languagechange
|
onoffline
WorkerGlobalScope/offline_event Firefox29+Safari8+ChromeNo
Opera?EdgeNo Edge (Legacy)?Internet ExplorerNo Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android? | offline
|
ononline
WorkerGlobalScope/online_event Firefox29+Safari8+ChromeNo
Opera?EdgeNo Edge (Legacy)?Internet ExplorerNo Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android? | online
|
onrejectionhandled
| rejectionhandled
|
onunhandledrejection
| unhandledrejection
|
DedicatedWorkerGlobalScope
インターフェイス
すべての現在のエンジンでサポートされています。
[Global =(Worker ,DedicatedWorker ),Exposed =DedicatedWorker ]
interface DedicatedWorkerGlobalScope : WorkerGlobalScope {
[Replaceable ] readonly attribute DOMString name ;
undefined postMessage (any message , sequence <object > transfer );
undefined postMessage (any message , optional StructuredSerializeOptions options = {});
undefined close ();
attribute EventHandler onmessage ;
attribute EventHandler onmessageerror ;
};
DedicatedWorkerGlobalScope
オブジェクトは、それに関連付けられた暗黙のMessagePort
があるかのように動作します。このポートはワーカーが作成されるときにセットアップされるチャネルの一部ですが、公開されません。このオブジェクトは、DedicatedWorkerGlobalScope
オブジェクトよりも前にガベージコレクトされることはありません。
そのポートが受信したすべてのメッセージは、直ちにDedicatedWorkerGlobalScope
オブジェクトにリターゲットされなければなりません。
dedicatedWorkerGlobal.name
DedicatedWorkerGlobalScope/name
すべての現在のエンジンでサポートされています。
dedicatedWorkerGlobalのnameを返します。つまり、
Worker
コンストラクターに渡された値です。主にデバッグに便利です。
dedicatedWorkerGlobal.postMessage(message [, transfer ])
DedicatedWorkerGlobalScope/postMessage
すべての現在のエンジンでサポートされています。
dedicatedWorkerGlobal.postMessage(message [, { transfer } ])
messageをクローンし、それをdedicatedWorkerGlobalに関連付けられたWorker
オブジェクトに送信します。transferは、クローンではなく転送するオブジェクトのリストとして渡すことができます。
dedicatedWorkerGlobal.close()
DedicatedWorkerGlobalScope/close
すべての現在のエンジンでサポートされています。
dedicatedWorkerGlobalを中止します。
nameゲッターステップは、thisのname
を返すことです。その値は、主にデバッグ目的で使用される、Workerコンストラクタを使用してワーカーに与えられた名前を表します。
postMessage(message,
transfer)およびpostMessage(message,
options)メソッドは、DedicatedWorkerGlobalScopeオブジェクトで
実行される場合、それがただちにそれぞれのpostMessage(message, transfer)およびpostMessage(message,
options)をポートで同じ引数で呼び出し、同じ戻り値を返すかのように動作します。
ワーカーを閉じるには、workerGlobalが与えられた場合、以下の手順を実行します:
workerGlobalのクローズフラグをtrueに設定します。(これにより、さらにタスクがキューに追加されることを防ぎます。)
close()メソッドのステップは、ワーカーを閉じることです。thisが与えられた場合。
以下は、イベントハンドラ(およびそれに対応するイベントハンドラのイベントタイプ)で、イベントハンドラのIDL属性として、DedicatedWorkerGlobalScope
インターフェイスを実装するオブジェクトによってサポートされる必要があります:
| イベントハンドラ | イベントハンドラのイベントタイプ |
|---|---|
onmessage
DedicatedWorkerGlobalScope/message_event すべての現在のエンジンでサポートされています。 Firefox3.5+Safari4+Chrome4+
Opera10.6+Edge79+ Edge (Legacy)12+Internet Explorer10+ Firefox Android?Safari iOS5+Chrome Android?WebView Android37+Samsung Internet?Opera Android11.5+ | message
|
onmessageerror
DedicatedWorkerGlobalScope/messageerror_event すべての現在のエンジンでサポートされています。 Firefox57+Safari16.4+Chrome60+
Opera?Edge79+ Edge (Legacy)18Internet Explorerなし Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android47+ | messageerror
|
SharedWorkerGlobalScope
インターフェイス
現在のすべてのエンジンでサポートされています。
[Global =(Worker ,SharedWorker ),Exposed =SharedWorker ]
interface SharedWorkerGlobalScope : WorkerGlobalScope {
[Replaceable ] readonly attribute DOMString name ;
undefined close ();
attribute EventHandler onconnect ;
};
SharedWorkerGlobalScope
オブジェクトには、関連付けられたコンストラクタのオリジン、コンストラクタのURL、
クレデンシャルがあります。これらは、SharedWorkerGlobalScope
オブジェクトが作成されるときに、ワーカーを実行する
アルゴリズムで初期化されます。
共有ワーカーは、それぞれの接続ごとにconnect
イベントを介してSharedWorkerGlobalScope
オブジェクトにメッセージポートを受け取ります。
sharedWorkerGlobal.name
現在のすべてのエンジンでサポートされています。
sharedWorkerGlobal の name、
つまりSharedWorker
コンストラクタに渡された値を返します。同じ名前を再利用することで、複数のSharedWorker
オブジェクトが同じ共有ワーカー(およびSharedWorkerGlobalScope)に対応することができます。
sharedWorkerGlobal.close()
現在のすべてのエンジンでサポートされています。
sharedWorkerGlobal を中止します。
name の getter のステップは、this の name
を返すことです。
その値は、SharedWorker
コンストラクタを使用してワーカーの参照を取得するために使用できる名前を表します。
close() メソッドのステップは、ワーカーを閉じる ことです。
this が与えられた場合。
以下は、イベントハンドラ
(およびそれに対応するイベントハンドラ
イベントタイプ)であり、
イベントハンドラ IDL 属性
として、SharedWorkerGlobalScope
インターフェイスを実装するオブジェクトでサポートされなければなりません。
| イベントハンドラ | イベントハンドラ イベントタイプ |
|---|---|
onconnect
SharedWorkerGlobalScope/connect_event 現在のすべてのエンジンでサポートされています。 Firefox29+Safari16+Chrome4+
Opera10.6+Edge79+ Edge (レガシー)?Internet Explorer非対応 Firefox Android?Safari iOS16+Chrome Android?WebView Android37+Samsung Internet?Opera Android11+ | connect
|
ワーカーイベントループの タスクキューには、タスクとしてイベント、コールバック、およびネットワーク活動のみが含まれます。 これらのワーカーイベントループは、 ワーカーを実行するアルゴリズムによって作成されます。
各WorkerGlobalScopeオブジェクト
にはclosingフラグがあり、
これは初期状態では必ず false でなければなりませんが、以下の処理モデルセクションのアルゴリズムにより true に設定されることがあります。
一度WorkerGlobalScopeの
closingフラグが
true に設定されると、イベントループの
タスクキューはそれ以降に追加される
すべてのタスクを破棄しなければなりません
(既にキューにあるタスクは別段の指示がない限り影響を受けません)。実質的には、closingフラグが
true になると、タイマーが停止し、すべての保留中のバックグラウンド操作の通知が中断されるなどの影響があります。
ワーカーは、メッセージチャネル
およびそれらの
MessagePort
オブジェクトを介して、他のワーカーやWindowと通信します。
各WorkerGlobalScope
オブジェクトワーカーグローバルスコープには、
ワーカーのポートのリストがあり、これは他のポートと絡み合っており、その中の1つのポートがワーカーグローバルスコープによって所有されている
MessagePort
オブジェクトのすべてを含みます。このリストには、
専用ワーカーの場合には暗黙のMessagePortも含まれます。
ワーカーを作成または取得する際にoという
環境設定オブジェクトが与えられた場合、
追加すべき関連オーナーはoによって指定されたグローバルオブジェクトのタイプに依存します。
もしoのグローバルオブジェクトがWorkerGlobalScope
オブジェクトである場合(つまり、ネストされた専用ワーカーを作成している場合)、関連オーナーはそのグローバルオブジェクトです。
それ以外の場合、oのグローバルオブジェクトがWindow
オブジェクトであるため、
関連オーナーはそのWindowの関連付けられたDocumentです。
ワーカーは、そのWorkerGlobalScopeの
オーナーセットが空でない場合、または次の場合に許容されるワーカーとされます:
WorkerGlobalScope
オブジェクトがSharedWorkerGlobalScopeオブジェクト
である場合(つまり、そのワーカーが共有ワーカーである場合)、
この定義の第2部は、ページが読み込まれている間、共有ワーカーが短時間生き残ることを可能にします。 これは、そのページが再び共有ワーカーに接続する可能性があるためです。 これにより、ユーザーが同じサイト内のページ間を移動する際に、ユーザーエージェントが共有ワーカーの再起動のコストを回避する方法として使用できます。
ワーカーは、そのオーナーのいずれかが
完全にアクティブである
Documentオブジェクトか、
アクティブな必要ワーカー
である場合、そのワーカーはアクティブな必要ワーカーとされます。
ワーカーは、そのアクティブな必要ワーカーであり、
それが未解決のタイマー、データベーストランザクション、またはネットワーク接続を持っている場合、またはその
ワーカーのポートのリストが空でない場合、
またはそのWorkerGlobalScopeが
実際にSharedWorkerGlobalScopeオブジェクトである場合
(つまり、そのワーカーが共有ワーカーである場合)、保護されたワーカーとされます。
ワーカーは、それがアクティブな必要ワーカーではなく、 しかし許容されるワーカーである場合、一時停止可能なワーカーとされます。
ユーザーエージェントがWorkerまたはSharedWorkerオブジェクトworkerを持つスクリプトのワーカーを実行する場合、URL url、環境設定オブジェクト
outside settings、MessagePort outside
port、およびWorkerOptionsディクショナリoptionsを実行しなければなりません。
is sharedがtrueである場合はworkerがSharedWorkerオブジェクトであり、そうでない場合はfalseとします。
ownerをoutside settingsに基づいて追加する関連オーナーにします。
unsafeWorkerCreationTimeを安全でない共有現在時刻にします。
agentをoutside settingsおよびis sharedを指定して専用/共有ワーカーエージェントを取得する結果とします。このエージェント内でこれらのステップを実行します。
realm execution contextをagentおよび次のカスタマイズを指定して新しい領域を作成する結果とします:
グローバルオブジェクトについて、is sharedがtrueである場合、新しいSharedWorkerGlobalScopeオブジェクトを作成します。そうでない場合は、新しいDedicatedWorkerGlobalScopeオブジェクトを作成します。
worker global scopeをrealm execution contextのRealmコンポーネントのグローバルオブジェクトにします。
これは前のステップで作成されたDedicatedWorkerGlobalScopeまたはSharedWorkerGlobalScopeオブジェクトです。
realm execution context、outside settings、unsafeWorkerCreationTimeを指定してワーカー環境設定オブジェクトを設定するを実行し、その結果をinside settingsとします。
worker global scopeのnameをoptionsのnameメンバーの値に設定します。
is sharedがtrueである場合、次のステップを実行します:
worker global scopeのコンストラクタのオリジンをoutside settingsのオリジンに設定します。
worker global scopeのコンストラクタのURLをurlに設定します。
worker global scopeのタイプをoptionsのtypeメンバーの値に設定します。
worker global scopeのクレデンシャルをoptionsのcredentialsメンバーの値に設定します。
destinationをis
sharedがtrueである場合"sharedworker"、そうでない場合"worker"とします。
optionsのtypeメンバーの値に応じてscriptを取得します:
classic"
module"
credentialsメンバーの値、inside
settingsを指定し、以下に定義されたonCompleteとperformFetchを使用します。
いずれの場合も、フェッチフックを実行するをrequest、isTopLevel、processCustomFetchResponseを指定して実行します:
isTopLevelがfalseである場合、フェッチをrequestで実行し、processResponseConsumeBodyをprocessCustomFetchResponseに設定し、これらのステップを中止します。
フェッチをrequestで実行し、processResponseConsumeBodyを次のステップに設定し、response response、null、失敗、またはバイトシーケンス bodyBytesを指定します:
ワーカーグローバルスコープのポリシーコンテナを初期化するをworker global scope、response、およびinside settingsを指定して実行します。
グローバルオブジェクトに対するCSP初期化を実行するアルゴリズムがworker
global scopeに対して"Blocked"を返す場合、responseをネットワークエラーに設定します。[CSP]
worker global scopeの埋め込みポリシーの値がクロスオリジン分離に対応しており、is
sharedがtrueである場合、agentのエージェントクラスターのクロスオリジン分離モードを"論理的"または"具体的"に設定します。選択されるものは実装定義です。
これはエージェントクラスターが作成された時点で設定されるべきであり、このセクションの再設計が必要です。
グローバルオブジェクトの埋め込みポリシーを確認するをworker global scope、outside settings、およびresponseに対して実行した結果がfalseである場合、responseをネットワークエラーに設定します。
worker global scopeのクロスオリジン分離能力をagentのエージェントクラスターのクロスオリジン分離モードが"具体的"である場合はtrueに設定します。
is sharedがfalseであり、ownerのクロスオリジン分離能力がfalseである場合、worker global scopeのクロスオリジン分離能力をfalseに設定します。
is sharedがfalseであり、responseのURLのスキームが"data"である場合、worker
global scopeのクロスオリジン分離能力をfalseに設定します。
これは現時点では保守的なデフォルトであり、ワーカー全般、およびdata:
URLワーカーの特定の扱い(所有者からはクロスオリジンである)が、許可ポリシーの文脈でどのように扱われるかを検討している段階です。詳細はw3c/webappsec-permissions-policy
issue #207を参照してください。
processCustomFetchResponseをresponseおよびbodyBytesを指定して実行します。
いずれの場合も、scriptが与えられた場合のonCompleteを次のステップにします:
scriptがnullであるか、scriptの再スローするエラーがnullでない場合:
グローバルタスクをキューに追加するをworkerの関連グローバルオブジェクトを指定してイベントを発生させるために実行し、workerにerrorという名前のイベントを発生させます。
環境破棄ステップをinside settingsに対して実行します。
これらのステップを中止します。
workerをworker global scopeと関連付けます。
inside portを新しい MessagePortオブジェクトに設定し、inside
settingsの領域に設定します。
inside portをworker global scopeと関連付けます。
エンタングル outside portとinside portを実行します。
新しいWorkerLocationオブジェクトを作成し、それをworker
global scopeと関連付けます。
孤立したワーカーの終了: ワーカーを監視し、保護されたワーカーでなくなった時点から遅くとも許容されるワーカーでなくなった時点までに、worker global scopeのclosingフラグがtrueに設定されるようにします。
ワーカーの一時停止: ワーカーを監視し、worker global scopeのclosingフラグがfalseであり、ワーカーが一時停止可能なワーカーである場合、ユーザーエージェントがそのワーカー内でのスクリプトの実行を一時停止し、closingフラグがtrueに切り替わるか、ワーカーが一時停止可能なワーカーでなくなるまで実行を中止します。
inside settingsの実行準備フラグを設定します。
scriptがクラシックスクリプトである場合、クラシックスクリプトを実行する scriptを実行します。そうでない場合、それはモジュールスクリプトであり、モジュールスクリプトを実行する scriptを実行します。
通常の結果を返すか、例外により失敗する可能性がある他に、これはスクリプトの実行を中止するアルゴリズムによりワーカーを終了することで途中で中断される可能性があります。
outside portのポートメッセージキューを有効にします。
is sharedがfalseである場合、ワーカーの暗黙のポートのポートメッセージキューを有効にします。
is sharedがtrueである場合、グローバルタスクをキューに追加するをworker global
scopeを指定してイベントを発生させるために実行し、connectという名前のイベントをworker
global scopeに発生させます。これには、MessageEventを使用し、data属性を空の文字列に初期化し、ports属性をinside
portを含む新しいフローズンアレイに初期化し、source属性をinside
portに初期化します。
クライアントメッセージキューを、関連するサービスワーカークライアントがworker
global scopeの関連設定オブジェクトであるServiceWorkerContainerオブジェクトの有効にします。
イベントループ: inside settingsによって指定された責任イベントループを実行し、それが破棄されるまで実行します。
タスクによって実行されるイベントの処理またはコールバックの実行は、スクリプトの実行を中止するアルゴリズムによりワーカーを終了することで途中で中断される可能性があります。
ワーカー処理モデルは、イベントループが破棄されるまでこのステップに留まります。これは、イベントループ処理モデルで説明されているように、closingフラグがtrueに設定された後に発生します。
クリアする worker global scopeのアクティブタイマーのマップを設定します。
ユーザーエージェントがワーカーを終了するときは、ワーカーのメインループ(上記の「ワーカーを実行する」処理モデル)と並行して、次のステップを実行しなければなりません:
ワーカーのWorkerGlobalScopeオブジェクトのclosingフラグをtrueに設定します。
ワーカーのWorkerGlobalScopeオブジェクトの関連するエージェントのイベントループのタスクキューにキューされているタスクがある場合、それらを処理せずに破棄します。
現在ワーカー内で実行中のスクリプトを中止します。
ワーカーのWorkerGlobalScopeオブジェクトが実際にDedicatedWorkerGlobalScopeオブジェクトである場合(つまり、そのワーカーが専用ワーカーである場合)、ワーカーの暗黙のポートと絡み合っているポートのポートメッセージキューを空にします。
ユーザーエージェントは、ワーカーがアクティブな必要ワーカーでなくなり、そのclosingフラグがtrueに設定された後もワーカーが実行を続けている場合、ワーカーを終了するアルゴリズムを呼び出すことがあります。
ワーカーのスクリプトの1つで未処理の実行時スクリプトエラーが発生した場合、そのエラーが以前のスクリプトエラーの処理中に発生しなかった場合、ユーザーエージェントはワーカーのWorkerGlobalScopeオブジェクトに対して報告します。
AbstractWorkerミックスインinterface mixin AbstractWorker {
attribute EventHandler onerror ;
};
次のものは、AbstractWorkerインターフェイスを実装するオブジェクトによってサポートされなければならないイベントハンドラ(およびそれに対応するイベントハンドライベントタイプ)です。これらはイベントハンドラIDL属性としてサポートされなければなりません。
| イベントハンドラ | イベントハンドライベントタイプ |
|---|---|
onerror
現在のすべてのエンジンでサポートされています。 Firefox44+Safari11.1+Chrome40+
Opera?Edge79+ Edge (レガシー)17+Internet Explorer非対応 Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android? 現在のすべてのエンジンでサポートされています。 Firefox29+Safari16+Chrome5+
Opera10.6+Edge79+ Edge (レガシー)?Internet Explorer非対応 Firefox Android33+Safari iOS16+Chrome Android非対応WebView Android?Samsung Internet4.0–5.0Opera Android11–14 現在のすべてのエンジンでサポートされています。 Firefox3.5+Safari4+Chrome4+
Opera10.6+Edge79+ Edge (レガシー)12+Internet Explorer10+ Firefox Android?Safari iOS5+Chrome Android?WebView Android?Samsung Internet?Opera Android11+ | error
|
ワーカー環境設定オブジェクトを設定するには、JavaScript 実行コンテキスト execution context、環境設定オブジェクト outside settings、および数値unsafeWorkerCreationTimeが与えられます:
inherited originをoutside settingsのオリジンに設定します。
realmをexecution contextのRealmコンポーネントの値に設定します。
worker global scopeをrealmのグローバルオブジェクトに設定します。
settings objectを新しい環境設定オブジェクトに設定し、そのアルゴリズムを以下のように定義します:
execution contextを返します。
worker global scopeのモジュールマップを返します。
worker global scopeのURLを返します。
worker global scopeのURLのスキームが"data"である場合、不透明なオリジンを返し、それ以外の場合はinherited
originを返します。
worker global scopeのポリシーコンテナを返します。
worker global scopeのクロスオリジン分離能力を返します。
unsafeWorkerCreationTimeをworker global scopeのクロスオリジン分離能力と共に粗くする結果を返します。
settings objectのIDを新しい不透明な文字列に設定し、作成URLをworker global scopeのURLに、トップレベル作成URLをnullに、ターゲットブラウジングコンテキストをnullに、アクティブサービスワーカーをnullに設定します。
worker global scopeがDedicatedWorkerGlobalScopeオブジェクトである場合、settings
objectのトップレベルオリジンをoutside
settingsのトップレベルオリジンに設定します。
それ以外の場合は、settings objectのトップレベルオリジンを実装定義の値に設定します。
クライアントサイドストレージのパーティショニングで最新の適切な定義を参照してください。
realmの[[HostDefined]]フィールドをsettings objectに設定します。
settings objectを返します。
Workerインターフェイス現在のすべてのエンジンでサポートされています。
[Exposed =(Window ,DedicatedWorker ,SharedWorker )]
interface Worker : EventTarget {
constructor ((TrustedScriptURL or USVString ) scriptURL , optional WorkerOptions options = {});
undefined terminate ();
undefined postMessage (any message , sequence <object > transfer );
undefined postMessage (any message , optional StructuredSerializeOptions options = {});
attribute EventHandler onmessage ;
attribute EventHandler onmessageerror ;
};
dictionary WorkerOptions {
WorkerType type = "classic";
RequestCredentials credentials = "same-origin"; // credentials is only used if type is "module"
DOMString name = "";
};
enum WorkerType { "classic" , "module" };
Worker includes AbstractWorker ;
worker = new Worker(scriptURL [, options ])
現在のすべてのエンジンでサポートされています。
新しいWorkerオブジェクトを返します。scriptURLはバックグラウンドでフェッチされ実行され、新しいグローバル環境が作成され、workerがそのコミュニケーションチャネルを表します。optionsを使用して、主にデバッグ目的でそのグローバル環境の名前をnameオプションで定義することができます。また、この新しいグローバル環境が
JavaScript
モジュールをサポートするようにする(type: "module"を指定)こともでき、それが指定されている場合、scriptURLがcredentialsオプションを通じてどのようにフェッチされるかを指定することもできます。
worker.terminate()
現在のすべてのエンジンでサポートされています。
worker.postMessage(message [, transfer ])
現在のすべてのエンジンでサポートされています。
terminate()メソッドは、呼び出されたとき、ワーカーを終了するアルゴリズムをそのオブジェクトに関連付けられたワーカーに対して実行する必要があります。
Workerオブジェクトは、暗黙のうちにMessagePortを関連付けているかのように動作します。このポートはワーカーが作成されたときに設定されたチャンネルの一部ですが、公開されません。このオブジェクトは、Workerオブジェクトより前にガベージコレクトされることは決してありません。
そのポートによって受信されたすべてのメッセージは、直ちにWorkerオブジェクトに再ターゲットされなければなりません。
postMessage(message, transfer)およびpostMessage(message, options)メソッドは、Workerオブジェクトに関連するポートで同名のメソッドが直ちに呼び出され、同じ引数を使用し、同じ戻り値を返すかのように動作します。
postMessage()メソッドの最初の引数は構造化データを持つことができます:
worker. postMessage({ opcode: 'activate' , device: 1938 , parameters: [ 23 , 102 ]});
以下はイベントハンドラー(およびそれに対応するイベントハンドラーのイベントタイプ)であり、Workerインターフェイスを実装するオブジェクトがサポートしなければならないものです:
| イベントハンドラー | イベントハンドラーのイベントタイプ |
|---|---|
onmessage
| message
|
onmessageerror
| messageerror
|
Worker(scriptURL, options)コンストラクターが呼び出されると、ユーザーエージェントは次の手順を実行しなければなりません:
compliantScriptURLを信頼された型に準拠する文字列を取得するアルゴリズムをTrustedScriptURL、thisの関連するグローバルオブジェクト、scriptURL、"Worker constructor"、および"script"と共に実行した結果に設定します。
outside settingsを現在の設定オブジェクトに設定します。
worker URLをcompliantScriptURLを与えたURLのエンコーディングと解析の結果に設定します。
同一オリジンのURL(blob:URLを含む)は使用できます。data:
URL も使用できますが、不透明なオリジンを持つワーカーが作成されます。
worker URLが失敗した場合は、"SyntaxError" DOMExceptionをスローします。
workerを新しいWorkerオブジェクトに設定します。
outside portをnew MessagePortにoutside
settingsのrealmに設定します。
outside portをworkerに関連付けます。
このステップを並行して実行します:
ワーカーを実行するをworker、worker URL、outside settings、outside port、およびoptionsに与えて実行します。
workerを返します。
SharedWorkerインターフェイス
現在のすべてのエンジンでサポートされています。
[Exposed =Window ]
interface SharedWorker : EventTarget {
constructor ((TrustedScriptURL or USVString ) scriptURL , optional (DOMString or WorkerOptions ) options = {});
readonly attribute MessagePort port ;
};
SharedWorker includes AbstractWorker ;
sharedWorker = new SharedWorker(scriptURL [, name ])
現在のすべてのエンジンでサポートされています。
新しいSharedWorkerオブジェクトを返します。scriptURLはバックグラウンドでフェッチおよび実行され、sharedWorkerが通信チャネルを表す新しいグローバル環境が作成されます。nameは、そのグローバル環境のnameを定義するために使用できます。
sharedWorker = new SharedWorker(scriptURL [, options ])
新しいSharedWorkerオブジェクトを返します。scriptURLはバックグラウンドでフェッチおよび実行され、sharedWorkerが通信チャネルを表す新しいグローバル環境が作成されます。optionsは、そのグローバル環境のnameをnameオプションを介して定義するために使用できます。また、この新しいグローバル環境がJavaScriptモジュールをサポートすることを確実にし(type: "module"を指定)、指定された場合、scriptURLがcredentialsオプションを通じてどのようにフェッチされるかを指定するために使用できます。なお、optionsのtypeまたはcredentialsの値が既存の共有ワーカーと一致しない場合、返されたsharedWorkerはエラーイベントを発生させ、既存の共有ワーカーに接続しません。
sharedWorker.port
現在のすべてのエンジンでサポートされています。
sharedWorkerのMessagePortオブジェクトを返します。これを使用して、グローバル環境と通信できます。
port
属性は、オブジェクトのコンストラクタによって割り当てられた値を返さなければなりません。これは、共有ワーカーとの通信に使用される MessagePort
を表します。
ユーザーエージェントには、 共有ワーカーマネージャー という関連する要素があり、これは 新しい並列キューの開始 の結果です。
各ユーザーエージェントには、シンプルさを保つために1つの 共有ワーカーマネージャー があります。実装は、 オリジン ごとに1つ使用することができ、その場合でも観察可能な違いはなく、より多くの並列性が可能になります。
SharedWorker(scriptURL, options)
コンストラクタが呼び出されたとき:
compliantScriptURL を 信頼された型に準拠した文字列を取得する アルゴリズムを TrustedScriptURL、this の 関連するグローバルオブジェクト、
scriptURL、「SharedWorkerコンストラクタ」および「script」を使用して実行した結果とします。
options が DOMString
の場合、options を新しい WorkerOptions
辞書に設定し、その name メンバーを options の値に設定し、他のメンバーはデフォルト値に設定します。
外部設定 を 現在の設定オブジェクト にします。
urlRecord を compliantScriptURL を基に 外部設定 に対して URLのエンコードと解析 の結果とします。
任意の 同一オリジン のURL ( blob:
URLを含む) を使用することができます。 data:
URL も使用できますが、それらは不透明なオリジンを持つワーカーを作成します。
urlRecord が失敗した場合、"SyntaxError" DOMException
をスローします。
worker を新しい SharedWorker
オブジェクトとして作成します。
外部ポート を 外部設定 の realm
で新しい 新しい MessagePort
として作成します。
worker の port
属性に 外部ポート を割り当てます。
callerIsSecureContext を 外部設定 が セキュアコンテキスト の場合にtrue、それ以外の場合にfalseとします。
外部ストレージキー を ストレージ以外の目的のためのストレージキーを取得 の結果とし、外部設定 を指定して実行します。
次の手順をキューに追加 し、 共有ワーカーマネージャー に追加します。
worker global scope をnullに設定します。
すべての SharedWorkerGlobalScope
オブジェクトのリストを反復します。
worker storage key を scope の 関連する設定オブジェクト に基づいて ストレージ以外の目的のためのストレージキーを取得 する結果とします。
次のすべてがtrueの場合:
name メンバーと等しい。次に:
worker global scope を scope に設定します。
中断します。
data:
URL は不透明なオリジンを持つワーカーを作成します。 コンストラクタオリジン
と コンストラクタURL
が比較されるため、同じ data:
URL を使用して、オリジン内で同じ SharedWorkerGlobalScope
オブジェクトにアクセスすることはできますが、同一オリジン制約を回避することはできません。
worker global scope がnullでないが、ユーザーエージェントが worker global scope によって表されるワーカーと outside settings の スクリプト 間の通信を許可しないように構成されている場合、 worker global scope をnullに設定します。
たとえば、ユーザーエージェントは特定の トップレベルトラバーサブル を他のすべてのページから分離する開発モードを持ち、その開発モード内のスクリプトが通常のブラウザーモードで実行されている共有ワーカーに接続することをブロックできる場合があります。
worker global scope がnullでない場合、その worker global scope の タイプ と クレデンシャル が options の値と一致するかどうかを確認します。一致しない場合、 タスクをキューに追加 し、 イベントを発火 させ、これらの手順を中止します。
worker global scope がnullでない場合、次のサブステップを実行します:
設定オブジェクト を worker global scope に関連する設定オブジェクトに設定します。
workerIsSecureContext を 設定オブジェクト が セキュアコンテキスト の場合にtrue、それ以外の場合にfalseとします。
workerIsSecureContext が callerIsSecureContext と一致しない場合、 タスクをキューに追加 し、 イベントを発火 させ、worker にエラーを発生させ、これらの手順を中止します。 [SECURE-CONTEXTS]
worker と worker global scope を関連付けます。
inside port を 設定オブジェクト の realm
で新しい 新しい MessagePort
として作成します。
outside port と inside port を 絡ませます。
タスクをキューに追加 し、 DOM操作タスクソース
を使用して イベントを発火 させ、 worker global scope に
connect
という名前のイベントを発生させ、 MessageEvent
を使用して、 data
属性を空の文字列に初期化し、ports
属性を inside port のみを含む新しい フローズン配列 に初期化し、source
属性を inside port に初期化します。
それ以外の場合、 並列で 、 ワーカーを実行 し、worker、 urlRecord、 外部設定、 外部ポート、および options を指定します。
worker を返します。
interface mixin NavigatorConcurrentHardware {
readonly attribute unsigned long long hardwareConcurrency ;
};
self.navigator.hardwareConcurrency
ユーザーエージェントが使用できる可能性のある論理プロセッサの数を返します。
navigator.hardwareConcurrency
属性のゲッターは、ユーザーエージェントが使用できる可能性のある論理プロセッサの数と1の間の値を返さなければなりません。これが判定できない場合、ゲッターは1を返さなければなりません。
ユーザーエージェントは、論理プロセッサの数を公開する方向に誤るべきであり、ワーカー の作成に制限がある場合や、フィンガープリントの可能性を制限したい場合など、ユーザーエージェント固有の制限がある場合にのみ、より低い値を使用する必要があります。
importScripts(...urls) メソッドの手順は次の通りです:
urlStrings を « » に設定します。
次の項目を繰り返します: urls の url ごとに。
次の結果を urlStrings に追加します: 信頼された型に準拠した文字列を取得 アルゴリズムを TrustedScriptURL、this の 関連するグローバルオブジェクト、url、「Worker importScripts」、および「script」を使用して実行します。
スクリプトをワーカーのグローバルスコープにインポート します。このとき、this と urlStrings を指定します。
スクリプトをワーカーのグローバルスコープにインポート するためには、 WorkerGlobalScope
オブジェクト worker global scope、リスト として スカラー値文字列 の
urls、およびオプションの フェッチフックを実行 します。
worker global scope の タイプ が "module"
の場合、TypeError
例外をスローします。
設定オブジェクト を 現在の設定オブジェクト に設定します。
urls が空の場合、何も返しません。
urlRecords を « » に設定します。
urls の url ごとに:
urlRecord を URLのエンコードと解析 の結果に設定します。このとき url を指定し、設定オブジェクト に相対して実行します。
urlRecord が失敗した場合、"SyntaxError" DOMException
をスローします。
次の項目を urlRecords に追加します: urlRecord。
urlRecords の urlRecord ごとに:
クラシックなワーカーインポートスクリプトをフェッチ します。このとき urlRecord と 設定オブジェクト を指定し、提供されている場合は performFetch を渡します。これが成功した場合、script を結果として設定します。それ以外の場合、例外を再スローします。
クラシックスクリプトを実行 します。script を指定し、エラー再スロー引数をtrueに設定します。
script は、返されるか、解析に失敗するか、例外をキャッチし損なうか、上記で定義されている ワーカーの終了 アルゴリズムによって 早期に中断 されるまで実行されます。
例外がスローされた場合、またはスクリプトが 早期に中断 された場合、これらの手順をすべて中断し、例外や中断が呼び出し元の スクリプト によって引き続き処理されるようにします。
Service Workers は、このアルゴリズムを独自の フェッチフックを実行 して実行する仕様の例です。[SW]
WorkerNavigator インターフェースすべての現在のエンジンでサポートされています。
navigator
属性は、WorkerGlobalScope
インターフェースの一部であり、ユーザーエージェント (クライアント) のアイデンティティと状態を表す WorkerNavigator
インターフェースのインスタンスを返さなければなりません。
[Exposed =Worker ]
interface WorkerNavigator {};
WorkerNavigator includes NavigatorID ;
WorkerNavigator includes NavigatorLanguage ;
WorkerNavigator includes NavigatorOnLine ;
WorkerNavigator includes NavigatorConcurrentHardware ;
WorkerLocation インターフェースすべての現在のエンジンでサポートされています。
すべての現在のエンジンでサポートされています。
[Exposed =Worker ]
interface WorkerLocation {
stringifier readonly attribute USVString href ;
readonly attribute USVString origin ;
readonly attribute USVString protocol ;
readonly attribute USVString host ;
readonly attribute USVString hostname ;
readonly attribute USVString port ;
readonly attribute USVString pathname ;
readonly attribute USVString search ;
readonly attribute USVString hash ;
};
WorkerLocation オブジェクトには、関連する WorkerGlobalScope オブジェクト(WorkerGlobalScope オブジェクト)が存在します。
すべての現在のエンジンでサポートされています。
href
のゲッター手順は、this の
WorkerGlobalScope オブジェクト の URL を シリアル化 して返すことです。
すべての現在のエンジンでサポートされています。
origin
のゲッター手順は、オリジンのシリアル化 を this の WorkerGlobalScope オブジェクト の
URL の オリジン から返すことです。
すべての現在のエンジンでサポートされています。
protocol のゲッター手順は、this の WorkerGlobalScope オブジェクト の
URL の スキーム の後に ":" を付けて返すことです。
すべての現在のエンジンでサポートされています。
host
のゲッター手順は次の通りです:
url を this の WorkerGlobalScope
オブジェクト の URL に設定します。
url の ホスト が null である場合、空の文字列を返します。
すべての現在のエンジンでサポートされています。
hostname のゲッター手順は次の通りです:
host を this の WorkerGlobalScope
オブジェクト の URL の ホスト に設定します。
host が null である場合、空の文字列を返します。
host を シリアル化 して返します。
すべての現在のエンジンでサポートされています。
port
のゲッター手順は次の通りです:
port を this の WorkerGlobalScope
オブジェクト の URL の ポート に設定します。
port が null である場合、空の文字列を返します。
port を シリアル化 して返します。
すべての現在のエンジンでサポートされています。
pathname のゲッター手順は、URL パスのシリアル化 の結果を、this の WorkerGlobalScope オブジェクト の
URL から返すことです。
すべての現在のエンジンでサポートされています。
search
のゲッター手順は次の通りです:
query を this の WorkerGlobalScope
オブジェクト の URL の クエリ に設定します。
query が null または空の文字列である場合、空の文字列を返します。
query の前に "?" を付けて返します。
すべての現在のエンジンでサポートされています。
hash
のゲッター手順は次の通りです:
fragment を this の WorkerGlobalScope
オブジェクト の URL の フラグメント に設定します。
fragment が null または空の文字列である場合、空の文字列を返します。
fragment の前に "#" を付けて返します。
このセクションは規範的ではありません。
ワークレットは、メインのJavaScript実行環境とは独立してスクリプトを実行するための仕様インフラストラクチャであり、特定の実装モデルを必要としません。
ここで指定されているワークレットインフラストラクチャは、ウェブ開発者が直接使用することはできません。その代わり、他の仕様がそれを基にして、ブラウザの実装パイプラインの特定の部分で実行するために特化した、直接使用可能なワークレットタイプを作成します。
このセクションは規範的ではありません。
レンダリングや、オーディオ出力のような実装パイプラインの他の重要な部分に拡張ポイントを設けることは難しいです。もし、拡張ポイントが Window
で利用可能なAPIへの完全なアクセスを許可するものであった場合、エンジンは、これらのフェーズの途中で何が起こるかについての従来の前提を放棄する必要があります。たとえば、レイアウトフェーズ中に、レンダリングエンジンはDOMが変更されないことを前提としています。
さらに、Window 環境で拡張ポイントを定義すると、ユーザーエージェントは Window
オブジェクトと同じスレッドで作業を行うことに制限されます。(実装がスレッドセーフなAPIを可能にするための複雑で高コストなインフラストラクチャを追加し、スレッドジョイン保証を提供しない限り)
ワークレットは、ユーザーエージェントが現在依存している保証を維持しながら、拡張ポイントを許可するために設計されています。これは、WorkletGlobalScope
のサブクラスに基づいた新しいグローバル環境を通じて行われます。
ワークレットは、ウェブワーカーに似ています。ただし、以下の点が異なります:
スレッド非依存です。つまり、ワーカーのように専用の別スレッドで実行されるようには設計されていません。実装はワークレットを任意の場所で実行できます(メインスレッドを含む)。
並列処理のために、グローバルスコープの複数の重複インスタンスを作成することができます。
イベントベースのAPIを使用しません。代わりに、クラスがグローバルスコープに登録され、そのメソッドがユーザーエージェントによって呼び出されます。
グローバルスコープ上のAPIサーフェスが縮小されています。
その グローバルオブジェクト の寿命は、他の仕様によって定義され、しばしば 実装依存 の方法で決定されます。
ワークレットは比較的高いオーバーヘッドがあるため、慎重に使用することが推奨されます。このため、特定の WorkletGlobalScope
は、複数の別々のスクリプト間で共有されることが期待されます。(これは、1つの Window
が複数の別々のスクリプト間で共有されるのと似ています。)
ワークレットは、異なるユースケースに対応する汎用技術です。たとえば、CSS Painting API で定義されたワークレットは、ステートレスで冪等性を持ち、短時間で完了する計算のための拡張ポイントを提供しますが、これには特別な考慮事項があります。Web Audio API で定義されたワークレットは、ステートフルで長時間動作する操作のために使用されます。[CSSPAINT] [WEBAUDIO]
ワークレットを使用するいくつかの仕様は、ユーザーエージェントが複数のスレッドにわたって作業を並列化したり、必要に応じてスレッド間で作業を移動したりすることを可能にすることを目的としています。これらの仕様では、ユーザーエージェントがWeb開発者が提供するクラスのメソッドを実装依存の順序で呼び出す場合があります。
この結果、相互運用性の問題を防ぐために、そのようなWorkletGlobalScopeにクラスを登録する著者は、コードを冪等にする必要があります。つまり、クラスのメソッドまたはメソッド群は、特定の入力が与えられた場合に同じ出力を生成する必要があります。
この仕様は、著者が冪等な方法でコードを書くことを奨励するために、以下の技術を使用しています:
グローバルオブジェクトへの参照が利用できません(すなわち、WorkletGlobalScope上にselfに相当するものはありません)。
ワークレットが最初に仕様化されたとき、これは意図されたものでしたが、globalThisの導入により、もはや真実ではなくなりました。詳細については、issue #6059をご覧ください。
コードはモジュールスクリプトとしてロードされます。これにより、コードは厳密モードで実行され、共有されたthisがグローバルプロキシを参照しないようになります。
これらの制限により、2つの異なるスクリプトがグローバルオブジェクトのプロパティを使用して状態を共有することを防ぐのに役立ちます。
さらに、ワークレットを使用し、実装依存の動作を許可することを意図している仕様は、次のことを守る必要があります:
これらの仕様は、ユーザーエージェントが各WorkletGlobalScopeインスタンスに対して常に少なくとも2つのWorkletインスタンスを持ち、クラスのメソッドまたはメソッド群をランダムに特定のWorkletGlobalScopeインスタンスに割り当てることを要求する必要があります。これらの仕様は、メモリ制約下でオプトアウトを提供することができます。
これらの仕様は、ユーザーエージェントが任意のタイミングでWorkletGlobalScopeのサブクラスのインスタンスを作成および破棄できるようにする必要があります。
ワークレットを使用するいくつかの仕様は、ユーザーエージェントの状態に基づいて、Web開発者が提供するクラスのメソッドを呼び出すことができます。スレッド間の並行性を高めるために、ユーザーエージェントは将来の状態に基づいてメソッドを推測的に呼び出すことがあります。
これらの仕様では、ユーザーエージェントが任意のタイミングで、任意の引数を使用して(現在のユーザーエージェントの状態に対応するものだけではなく)これらのメソッドを呼び出すことができます。そのような推測的評価の結果は、すぐには表示されませんが、ユーザーエージェントの状態が推測された状態と一致した場合に使用するためにキャッシュされることがあります。これにより、ユーザーエージェントとワークレットスレッド間の並行性が向上します。
この結果、ユーザーエージェント間の相互運用性リスクを防ぐために、そのようなWorkletGlobalScopeにクラスを登録する著者は、コードをステートレスにする必要があります。つまり、メソッドの呼び出しの唯一の効果はその結果であり、可変状態の更新などの副作用ではないべきです。
コードの冪等性を奨励するのと同じ技術が、著者がステートレスなコードを書くことを奨励します。
このセクションは規範的ではありません。
これらの例では、フェイクワークレットを使用します。Windowオブジェクトは、独自のFakeWorkletGlobalScopeコレクション内でコードを実行する、2つのWorkletインスタンスを提供します:
partial interface Window {
[SameObject , SecureContext ] readonly attribute Worklet fakeWorklet1 ;
[SameObject , SecureContext ] readonly attribute Worklet fakeWorklet2 ;
};
各Windowには、2つのWorkletインスタンス、フェイクワークレット1とフェイクワークレット2があります。これらの両方には、ワークレットグローバルスコープタイプがFakeWorkletGlobalScopeに設定され、ワークレット送信先タイプが「fakeworklet」に設定されています。ユーザーエージェントは、ワークレットごとに少なくとも2つのFakeWorkletGlobalScopeインスタンスを作成する必要があります。
「fakeworklet」は、FetchのFetchにおける有効な[送信先]ではありません。しかし、これにより、実際のワークレットが通常、独自のワークレットタイプ固有の送信先を持つことを説明しています。[FETCH]
fakeWorklet1ゲッターステップは、thisのフェイクワークレット1を返すことです。
fakeWorklet2ゲッターステップは、thisのフェイクワークレット2を返すことです。
[Global =(Worklet ,FakeWorklet ),
Exposed =FakeWorklet ,
SecureContext ]
interface FakeWorkletGlobalScope : WorkletGlobalScope {
undefined registerFake (DOMString type , Function classConstructor );
};
各FakeWorkletGlobalScopeには登録されたクラスコンストラクターマップがあり、これは順序付きマップで、初期状態では空です。
registerFake(type, classConstructor)メソッドステップは、thisの登録されたクラスコンストラクターマップ[type]をclassConstructorに設定することです。
このセクションは規範的ではありません。
フェイクワークレット1にスクリプトを読み込むには、Web開発者は次のように記述します:
window. fakeWorklet1. addModule( 'script1.mjs' );
window. fakeWorklet1. addModule( 'script2.mjs' );
どのスクリプトが先にフェッチされ、実行されるかはネットワークのタイミングに依存します。これはscript1.mjsかscript2.mjsのどちらかになります。一般的に、ワークレットで読み込まれるように設計された、適切に記述されたスクリプトであれば、推測的評価に関する提案に従う限り、問題にはなりません。
Web開発者がスクリプトが正常に実行されていくつかのワークレットに読み込まれた後にのみタスクを実行したい場合、次のように記述できます:
Promise. all([
window. fakeWorklet1. addModule( 'script1.mjs' ),
window. fakeWorklet2. addModule( 'script2.mjs' )
]). then(() => {
// これらのスクリプトが読み込まれていることに依存する処理を行います。
});
スクリプトの読み込みに関するもう一つの重要なポイントは、読み込まれたスクリプトが、WorkletGlobalScopeごとに複数のWorklet内で実行できることです。これはコードの冪等性に関するセクションで説明されています。特に、上記の仕様ではフェイクワークレット1とフェイクワークレット2でこれを必要としています。したがって、次のようなシナリオを考えてみましょう:
// script.mjs
console. log( "FakeWorkletGlobalScopeからこんにちは!" );
// app.mjs
window. fakeWorklet1. addModule( "script.mjs" );
これは、ユーザーエージェントのコンソールに次のような出力を生成する可能性があります:
[fakeWorklet1#1] FakeWorkletGlobalScopeからこんにちは!
[fakeWorklet1#4] FakeWorkletGlobalScopeからこんにちは!
[fakeWorklet1#2] FakeWorkletGlobalScopeからこんにちは!
[fakeWorklet1#3] FakeWorkletGlobalScopeからこんにちは!
ユーザーエージェントが何らかの時点でFakeWorkletGlobalScopeの3番目のインスタンスを終了して再起動することを決定した場合、この際に再び[fakeWorklet1#3] FakeWorkletGlobalScopeからこんにちは!がコンソールに表示されます。
このセクションは規範的ではありません。
仮に、Web開発者がフェイクワークレットを使用する目的の一つが、ブール値の否定という高度に複雑なプロセスをカスタマイズすることであるとしましょう。彼らは次のようにカスタマイズを登録するかもしれません:
// script.mjs
registerFake( 'negation-processor' , class {
process( arg) {
return ! arg;
}
});
// app.mjs
window. fakeWorklet1. addModule( "script.mjs" );
そのように登録されたクラスを利用するために、フェイクワークレットの仕様は、Workletworkletを与えて、真の反対を見つけるアルゴリズムを定義することができます:
任意で、ワークレットグローバルスコープを作成します。
classConstructorを、workletGlobalScopeの登録されたクラスコンストラクターマップ["negation-processor"]に設定します。
classInstanceを、コールバック関数を構築する結果として、引数なしで生成します。
functionをclassInstanceのGet(classInstance,
"process")として取得します。例外があれば再スローします。
コールバック関数を呼び出す結果を返します。引数は「true」で、「rethrow」とし、コールバック this
値をclassInstanceに設定します。
別の、より良いかもしれない仕様アーキテクチャは、登録時に「process」プロパティを抽出し、registerFake()メソッドステップの一部としてFunctionに変換することです。
WorkletGlobalScopeのサブクラスは、特定のWorkletにロードされたコードが実行されるグローバルオブジェクトを作成するために使用されます。
[Exposed =Worklet , SecureContext ]
interface WorkletGlobalScope {};
他の仕様は、WorkletGlobalScopeをサブクラス化し、クラスを登録するためのAPIや、ワークレットタイプに特有の他のAPIを追加することを意図しています。
各WorkletGlobalScopeには、関連するモジュールマップがあります。これはモジュールマップで、最初は空です。
このセクションは規範ではありません。
各WorkletGlobalScopeは、それぞれ独自のワークレットエージェント内に含まれており、対応するイベントループがあります。しかし、実際には、これらのエージェントとイベントループの実装は他の多くとは異なると予想されます。
各WorkletGlobalScopeに対応するワークレットエージェントが存在します。これは理論上、各WorkletGlobalScopeインスタンスごとに別々のスレッドを使用する実装が可能であり、このレベルの並列性を許可するためにはエージェントを使用するのが最適だからです。しかし、これらの[[CanBlock]]値がfalseであるため、エージェントとスレッドが一対一である必要はありません。これにより、ワークレットにロードされたスクリプトを他の[[CanBlock]]がfalseのエージェント(例えば同一オリジンのウィンドウエージェント、「メインスレッド」)のコードを実行するスレッドで実行することも可能になります。これに対して、[[CanBlock]]がtrueであるために専用のオペレーティングシステムスレッドを必要とする専用ワーカーエージェントとは対照的です。
ワークレットのイベントループもまた特別です。これらは、addModule()に関連するタスク、ユーザーエージェントが作成者定義のメソッドを呼び出すタスク、そしてマイクロタスクのためにのみ使用されます。そのため、イベントループ処理モデルはすべてのイベントループが継続的に実行されることを規定していますが、実装はよりシンプルな戦略を使用して観察可能な同等の結果を達成することができ、これは単に作成者提供のメソッドを呼び出し、そのプロセスがマイクロタスクのチェックポイントを実行することに依存する形になります。
あるWorklet workletのために
worklet グローバルスコープを作成するには、次の手順に従います。
outsideSettingsをworkletの関連設定オブジェクトに設定します。
agentを、outsideSettingsを指定してworklet エージェントを取得する結果として設定し、そのエージェント内で残りの手順を実行します。
realmExecutionContextを、agentと次のカスタマイズを指定して新しいレルムを作成する結果として設定します:
グローバルオブジェクトとして、workletのworklet グローバルスコープタイプによって指定された新しいオブジェクトを作成します。
workletGlobalScopeを、realmExecutionContextのレルムコンポーネントのグローバルオブジェクトとして設定します。
insideSettingsを、realmExecutionContextとoutsideSettingsを指定してworklet 環境設定オブジェクトを設定する結果として設定します。
pendingAddedModulesを、workletの追加モジュールリストのクローンとして設定します。
runNextAddedModuleを次の手順として設定します:
pendingAddedModulesが空でない場合、次の手順を実行します:
moduleURLをpendingAddedModulesからデキューした結果として設定します。
scriptを指定して、moduleURL、insideSettings、workletのworklet 宛先タイプ、どの認証モード?、insideSettings、workletのモジュール応答マップを指定してworklet スクリプトグラフをフェッチするを実行します。
これは実際にはネットワークリクエストを行わず、単にworkletのモジュール応答マップから応答を再利用します。この手順の主な目的は、応答からworkletGlobalScope固有のモジュールスクリプトを作成することです。
確認:scriptが null でないことを確認します。フェッチが成功し、workletのモジュール応答マップがmoduleURLで最初に入力されたときにソーステキストが正常に解析されたためです。
scriptを指定してモジュールスクリプトを実行するを実行します。
runNextAddedModuleを実行します。
追加
workletGlobalScopeをoutsideSettingsのグローバルオブジェクトの関連Documentに追加します。
insideSettingsで指定された責任イベントループを実行します。
runNextAddedModuleを実行します。
あるWorkletGlobalScope
workletGlobalScopeに対して worklet
グローバルスコープを終了するには、次の手順に従います:
eventLoopが現在実行中のタスクを完了するまで待ちます。
eventLoopを破棄します。
workletGlobalScopeを、Documentのworklet グローバルスコープから削除します。
次の手順を使用して、ワークレット環境設定オブジェクトを設定します。これは、JavaScript 実行コンテキストの executionContext と、環境設定オブジェクトの outsideSettings に基づいて行われます:
origin を一意の 不透明なオリジン に設定します。
inheritedAPIBaseURL を outsideSettings の API ベース URL に設定します。
inheritedPolicyContainer を outsideSettings の ポリシーコンテナのクローン に設定します。
realm を executionContext のレルムコンポーネントの値に設定します。
workletGlobalScope を realm の グローバルオブジェクト に設定します。
settingsObject を新しい 環境設定オブジェクト に設定し、そのアルゴリズムを次のように定義します:
executionContext を返します。
workletGlobalScope の モジュールマップ を返します。
inheritedAPIBaseURL を返します。
ワーカーや他のグローバルスコープと異なり、ワークレットは単一のリソースから派生しません。代わりに、各自の URL を持つ複数のスクリプトが worklet.addModule()
によってグローバルスコープにロードされます。そのため、この API ベース URL
は他のグローバルスコープとは異なりますが、これまでのところ、ワークレットコードで利用可能な API は API ベース URL を使用していないため、問題にはなりません。
origin を返します。
inheritedPolicyContainer を返します。
TODO を返します。
settingsObject の id を新しい一意の不透明な文字列に設定し、作成 URL を inheritedAPIBaseURL に、トップレベル作成 URL を null に、トップレベルオリジン を outsideSettings のトップレベルオリジン に、ターゲット閲覧コンテキスト を null に、そしてアクティブなサービスワーカー を null に設定します。
realm の [[HostDefined]] フィールドを settingsObject に設定します。
settingsObject を返します。
Worklet クラスすべての最新エンジンでサポートされています。
Worklet クラスは、関連付けられた WorkletGlobalScope
にモジュールスクリプトを追加する機能を提供します。その後、ユーザーエージェントは WorkletGlobalScope
に登録されたクラスを作成し、そのメソッドを呼び出すことができます。
[Exposed =Window , SecureContext ]
interface Worklet {
[NewObject ] Promise <undefined > addModule (USVString moduleURL , optional WorkletOptions options = {});
};
dictionary WorkletOptions {
RequestCredentials credentials = "same-origin";
};
Worklet インスタンスを作成する仕様では、以下の事項を指定する必要があります:
ワークレットグローバルスコープタイプ を指定します。これは WorkletGlobalScope
を継承する Web IDL タイプでなければなりません。
ワークレット送信先タイプ を指定します。これは 送信先 であり、スクリプトを取得するときに使用されます。
await worklet.addModule(moduleURL[, { credentials }])
すべての最新エンジンでサポートされています。
moduleURL で指定された モジュールスクリプト を worklet のすべての グローバルスコープ にロードして実行します。ワークレットの種類によっては、このプロセスの一環として追加のグローバルスコープを作成することもできます。スクリプトが正常にロードされ、すべてのグローバルスコープで実行されると、返されたプロミスは完了します。
credentials
オプションは、スクリプト取得プロセスを変更するために クレデンシャルモード に設定できます。デフォルトは
"same-origin" です。
スクリプトまたはその依存関係の 取得 中に失敗が発生した場合、返されたプロミスは "AbortError" DOMException
で拒否されます。スクリプトまたはその依存関係の解析中にエラーが発生した場合、返されたプロミスは解析中に生成された例外で拒否されます。
Worklet は、リスト を持ち、 グローバルスコープ を含みます。これは、 Worklet の ワークレットグローバルスコープタイプ のインスタンスです。初期状態では空です。
Worklet は、 追加されたモジュールリスト を持ち、これは リスト であり、 URL
のリストです。初期状態では空で、このリストへのアクセスはスレッドセーフである必要があります。
Worklet は、 モジュールレスポンスマップ を持ち、これは 順序付きマップ であり、 URL から
"fetching" または タプル までのマップです。このマップには、 レスポンス およびレスポンスボディを表す バイト列 が含まれます。このマップは初期状態では空であり、アクセスはスレッドセーフである必要があります。
追加されたモジュールリスト と モジュールレスポンスマップ は、異なるタイミングで作成された WorkletGlobalScope
に対して、同じソーステキストに基づいて同等の モジュールスクリプト
を実行することを保証するために存在します。これにより、追加の WorkletGlobalScope
の作成が、著者にとって透明になります。
実際には、ユーザーエージェントがこれらのデータ構造とそれを参照するアルゴリズムをスレッドセーフなプログラミング技術を使用して実装することは期待されていません。代わりに、addModule()
が呼び出されたとき、ユーザーエージェントはメインスレッドでモジュールグラフを取得し、取得されたソーステキスト(つまり、 モジュールレスポンスマップ に含まれる重要なデータ)を、それぞれの WorkletGlobalScope
を持つスレッドに送信できます。
その後、ユーザーエージェントが Worklet の新しい WorkletGlobalScope を 作成
するとき、メインスレッドから新しい WorkletGlobalScope
を含むスレッドに、取得されたソーステキストのマップとエントリーポイントのリストを送信するだけです。
addModule(moduleURL, options)
メソッドのステップは以下の通りです:
outsideSettings を、 関連設定オブジェクト の値に設定します。 this の設定オブジェクトです。
moduleURLRecord を URL をエンコードして解析する 結果として、 moduleURL を相対的にして得ます。 outsideSettings を基準にします。
moduleURLRecord が失敗した場合、 拒否されたプロミスを返します。 "SyntaxError" DOMException
です。
promise を新しいプロミスに設定します。
以下のステップを 並行して 実行します:
グローバルスコープを作成します。 this の設定オブジェクトで作成します。
オプションで、追加のグローバルスコープインスタンスを 作成します。 this を使用します。具体的なワークレットとその仕様によって異なります。
作成プロセス ( ワークレットエージェント 内で行われるプロセスを含む) のすべてのステップが完了するのを待ち、次のステップに進みます。
addedSuccessfully を false に設定します。
各 workletGlobalScopeについて、
この グローバルスコープの
グローバルタスクをキューに追加し、ネットワーキングタスクソースに、workletGlobalScopeを与えて、ワークレットスクリプトグラフをフェッチし、moduleURLRecord、outsideSettings、この ワークレットデスティネーションタイプ、options["credentials"]、
workletGlobalScopeの関連設定オブジェクト、この モジュール応答マップを指定し、scriptに対して次の手順を実行します。
これらのフェッチのうち最初のものだけが実際にネットワークリクエストを実行します。その他の WorkletGlobalScope
用のものは、レスポンス
を再利用します。これは this の モジュールレスポンスマップ から取得されます。
script が null の場合:
グローバルタスクをキューに追加します。 ネットワークタスクソース に this の 関連するグローバルオブジェクト を使用して以下のステップを実行します。
pendingTasks が -1 でない場合:
pendingTasks を -1 に設定します。
promise を "AbortError"
DOMException
で拒否します。
これらのステップを中止します。
script の 再スローするエラー が null でない場合:
グローバルタスクをキューに追加します。 ネットワークタスクソース に this の 関連するグローバルオブジェクト を使用して以下のステップを実行します。
pendingTasks が -1 でない場合:
pendingTasks を -1 に設定します。
promise を script の 再スローするエラー で拒否します。
これらのステップを中止します。
addedSuccessfully が false の場合:
リストに追加します。 this の 追加されたモジュールリスト に moduleURLRecord を追加します。
addedSuccessfully を true に設定します。
script を指定して モジュールスクリプトを実行します。
グローバルタスクをキューに追加します。 ネットワークタスクソース に this の 関連するグローバルオブジェクト を使用して以下のステップを実行します。
pendingTasks が -1 でない場合:
pendingTasks を pendingTasks - 1 に設定します。
pendingTasks が 0 の場合、 promise を解決します。
promise を返します。
Workletのライフタイムには特別な考慮は必要なく、
それが属するオブジェクト、例えばWindow
に関連付けられています。
各Documentには、ワークレットグローバルスコープがあり、
これは初期状態では空のWorkletGlobalScopeのセットです。
WorkletGlobalScope
のライフタイムは、最低でもそのDocumentに関連付けられたワークレットグローバルスコープに含まれています。特に、Documentの破棄は、対応するWorkletGlobalScope
を終了させ、それをガベージコレクションの対象にすることができます。
さらに、ユーザーエージェントはいつでも特定のWorkletGlobalScope
を終了させることができます。ただし、対応するワークレットタイプを定義する仕様で別の指示がない限りです。たとえば、ワークレットエージェントのイベントループにタスクがキューに入っていない場合や、ユーザーエージェントがワークレットを使用する予定の保留中の操作がない場合、または無限ループや制限時間を超えるコールバックなどの異常な操作を検出した場合などに終了させることが考えられます。
最後に、特定のワークレットタイプの仕様は、特定のワークレットタイプに対してWorkletGlobalScope
を作成する
時期について、より具体的な詳細を提供することがあります。たとえば、ワークレットコードを呼び出す特定のプロセス中にこれを作成するなどです。これは例に示されています。
Support in all current engines.
This section is non-normative.
This specification introduces two related mechanisms, similar to HTTP session cookies, for storing name-value pairs on the client side. [COOKIES]
The first is designed for scenarios where the user is carrying out a single transaction, but could be carrying out multiple transactions in different windows at the same time.
Cookies don't really handle this case well. For example, a user could be buying plane tickets in two different windows, using the same site. If the site used cookies to keep track of which ticket the user was buying, then as the user clicked from page to page in both windows, the ticket currently being purchased would "leak" from one window to the other, potentially causing the user to buy two tickets for the same flight without noticing.
To address this, this specification introduces the sessionStorage
getter.
Sites
can add data to the session
storage, and it will be accessible to any page from the same site opened in that window.
For example, a page could have a checkbox that the user ticks to indicate that they want insurance:
< label >
< input type = "checkbox" onchange = "sessionStorage.insurance = checked ? 'true' : ''" >
I want insurance on this trip.
</ label >
A later page could then check, from script, whether the user had checked the checkbox or not:
if ( sessionStorage. insurance) { ... }
If the user had multiple windows opened on the site, each one would have its own individual copy of the session storage object.
The second storage mechanism is designed for storage that spans multiple windows, and lasts beyond the current session. In particular, web applications might wish to store megabytes of user data, such as entire user-authored documents or a user's mailbox, on the client side for performance reasons.
Again, cookies do not handle this case well, because they are transmitted with every request.
The localStorage
getter is
used to
access a page's local
storage area.
The site at example.com can display a count of how many times the user has loaded its page by putting the following at the bottom of its page:
< p >
You have viewed this page
< span id = "count" > an untold number of</ span >
time(s).
</ p >
< script >
if ( ! localStorage. pageLoadCount)
localStorage. pageLoadCount = 0 ;
localStorage. pageLoadCount = parseInt( localStorage. pageLoadCount) + 1 ;
document. getElementById( 'count' ). textContent = localStorage. pageLoadCount;
</ script >
Each site has its own separate storage area.
The localStorage
getter provides access
to shared state. This specification does not define the interaction with other agent clusters
in a multiprocess user agent, and authors are encouraged to assume that there is no locking
mechanism. A site could, for instance, try to read the value of a key, increment its value, then
write it back out, using the new value as a unique identifier for the session; if the site does
this twice in two different browser windows at the same time, it might end up using the same
"unique" identifier for both sessions, with potentially disastrous effects.
Support in all current engines.
Storage interface[Exposed =Window ]
interface Storage {
readonly attribute unsigned long length ;
DOMString ? key (unsigned long index );
getter DOMString ? getItem (DOMString key );
setter undefined setItem (DOMString key , DOMString value );
deleter undefined removeItem (DOMString key );
undefined clear ();
};
storage.length
Support in all current engines.
Returns the number of key/value pairs.
storage.key (n)
Support in all current engines.
Returns the name of the nth key, or null if n is greater than or equal to the number of key/value pairs.
value = storage.getItem (key)
Support in all current engines.
value = storage[key]
Returns the current value associated with the given key, or null if the given key does not exist.
storage.setItem (key, value)
Support in all current engines.
storage[key] = value
Sets the value of the pair identified by key to value, creating a new key/value pair if none existed for key previously.
Throws a "QuotaExceededError" DOMException
exception
if the new value couldn't be set. (Setting could fail if, e.g., the user has disabled
storage
for the site, or if the quota has been exceeded.)
Dispatches a storage
event
on Window objects
holding an equivalent Storage
object.
storage.removeItem (key)
Support in all current engines.
delete
storage[key]
Removes the key/value pair with the given key, if a key/value pair with the given key exists.
Dispatches a storage
event on Window
objects
holding an equivalent Storage
object.
storage.clear()
Support in all current engines.
Removes all key/value pairs, if there are any.
Dispatches a storage
event on Window
objects
holding an equivalent Storage
object.
A Storage object has an
associated:
local" or "session".
To reorder a Storage object
storage, reorder storage's map's
entries in an implementation-defined manner.
Unfortunate as it is, iteration order is not defined and can change upon most mutations.
To broadcast a Storage object
storage, given a key, oldValue, and newValue, run
these steps:
Let thisDocument be storage's relevant global object's associated
Document.
Let url be thisDocument's URL.
Let remoteStorages be all Storage objects
excluding
storage whose:
and, if type is
"session",
whose relevant
settings object's associated
Document's node
navigable's traversable
navigable is thisDocument's node
navigable's traversable
navigable.
For each remoteStorage of
remoteStorages: queue a global task on the DOM
manipulation task
source given remoteStorage's relevant global object to fire
an
event named storage
at
remoteStorage's relevant global
object, using StorageEvent,
with
key
initialized to key, oldValue
initialized to oldValue, newValue
initialized to newValue, url
initialized to url, and storageArea
initialized to
remoteStorage.
The Document
object
associated with the resulting task
is
not necessarily fully
active,
but events
fired
on such objects are ignored by the event
loop until the Document
becomes fully active
again.
The length
getter
steps are to return this's map's size.
The key(index)
method steps are:
If index is greater than or equal to this's map's size, then return null.
Let keys be the result of running get the keys on this's map.
Return keys[index].
The supported property names on a Storage object
storage
are the result of running get the
keys on
storage's map.
The getItem(key) method steps are:
The setItem(key,
value) method are:
Let oldValue be null.
Let reorder be true.
If value cannot be stored, then throw a
"QuotaExceededError" DOMException
exception.
The removeItem(key) method steps are:
The clear() method
steps are:
sessionStorage
getterinterface mixin WindowSessionStorage {
readonly attribute Storage sessionStorage ;
};
Window includes WindowSessionStorage ;
window.sessionStorage
Support in all current engines.
Returns the Storage
object associated with that window's origin's
session storage area.
Throws a "SecurityError" DOMException
if the
Document's
origin is an opaque origin or if the
request
violates a
policy decision
(e.g., if the user agent is configured to not allow the page to persist data).
A Document object
has an
associated
session storage holder, which is
null or a Storage
object. It is
initially null.
The
sessionStorage getter steps are:
If this's associated
Document's session storage holder is
non-null, then
return
this's associated
Document's session storage holder.
Let map be the result of running obtain a session storage bottle
map with this's relevant settings
object and
"sessionStorage".
If map is failure, then throw a "SecurityError"
DOMException.
Set this's associated
Document's session storage holder
to
storage.
Return storage.
After creating a new auxiliary browsing context and document, the session storage is copied over.
localStorage
getterinterface mixin WindowLocalStorage {
readonly attribute Storage localStorage ;
};
Window includes WindowLocalStorage ;
window.localStorage
Support in all current engines.
Returns the Storage
object
associated with window's origin's local
storage area.
Throws a "SecurityError" DOMException
if the
Document's origin is an opaque origin or if the
request
violates a
policy decision
(e.g., if the user agent is configured to not allow the page to persist data).
A Document object has
an
associated
local storage holder, which is null
or a Storage
object. It is
initially null.
The
localStorage getter steps are:
If this's associated
Document's local storage holder is
non-null,
then return
this's associated
Document's local storage holder.
Let map be the result of running obtain a local storage bottle
map
with this's relevant settings object
and
"localStorage".
If map is failure, then throw a "SecurityError"
DOMException.
Set this's associated
Document's local storage holder to
storage.
Return storage.
StorageEvent
interfaceSupport in all current engines.
[Exposed =Window ]
interface StorageEvent : Event {
constructor (DOMString type , optional StorageEventInit eventInitDict = {});
readonly attribute DOMString ? key ;
readonly attribute DOMString ? oldValue ;
readonly attribute DOMString ? newValue ;
readonly attribute USVString url ;
readonly attribute Storage ? storageArea ;
undefined initStorageEvent (DOMString type , optional boolean bubbles = false , optional boolean cancelable = false , optional DOMString ? key = null , optional DOMString ? oldValue = null , optional DOMString ? newValue = null , optional USVString url = "", optional Storage ? storageArea = null );
};
dictionary StorageEventInit : EventInit {
DOMString ? key = null ;
DOMString ? oldValue = null ;
DOMString ? newValue = null ;
USVString url = "";
Storage ? storageArea = null ;
};
event.key
Returns the key of the storage item being changed.
event.oldValue
Returns the old value of the key of the storage item whose value is being changed.
event.newValue
Returns the new value of the key of the storage item whose value is being changed.
event.url
Returns the URL of the document whose storage item changed.
event.storageArea
Returns the Storage
object
that was affected.
The key,
oldValue,
newValue,
url,
and storageArea
attributes must return the values they were initialized to.
The initStorageEvent(type, bubbles,
cancelable, key, oldValue, newValue, url,
storageArea) method must initialize the event in a manner analogous to the
similarly-named initEvent()
method. [DOM]
A third-party advertiser (or any entity capable of getting content distributed to multiple sites) could use a unique identifier stored in its local storage area to track a user across multiple sessions, building a profile of the user's interests to allow for highly targeted advertising. In conjunction with a site that is aware of the user's real identity (for example an e-commerce site that requires authenticated credentials), this could allow oppressive groups to target individuals with greater accuracy than in a world with purely anonymous web usage.
There are a number of techniques that can be used to mitigate the risk of user tracking:
User agents may restrict access to the localStorage
objects to scripts originating at the domain of the active
document of the top-level
traversable, for instance denying access to the
API for pages from other domains running in iframes.
User agents may, possibly in a manner configured by the user, automatically delete stored data after a period of time.
For example, a user agent could be configured to treat third-party local storage areas as session-only storage, deleting the data once the user had closed all the navigables that could access it.
This can restrict the ability of a site to track a user, as the site would then only be able to track the user across multiple sessions when they authenticate with the site itself (e.g. by making a purchase or logging in to a service).
However, this also reduces the usefulness of the API as a long-term storage mechanism. It can also put the user's data at risk, if the user does not fully understand the implications of data expiration.
If users attempt to protect their privacy by clearing cookies without also clearing data stored in the local storage area, sites can defeat those attempts by using the two features as redundant backup for each other. User agents should present the interfaces for clearing these in a way that helps users to understand this possibility and enables them to delete data in all persistent storage features simultaneously. [COOKIES]
User agents may allow sites to access session storage areas in an unrestricted manner, but require the user to authorize access to local storage areas.
User agents may record the origins of sites that contained content from third-party origins that caused data to be stored.
If this information is then used to present the view of data currently in persistent storage, it would allow the user to make informed decisions about which parts of the persistent storage to prune. Combined with a blocklist ("delete this data and prevent this domain from ever storing data again"), the user can restrict the use of persistent storage to sites that they trust.
User agents may allow users to share their persistent storage domain blocklists.
This would allow communities to act together to protect their privacy.
While these suggestions prevent trivial use of this API for user tracking, they do not block it altogether. Within a single domain, a site can continue to track the user during a session, and can then pass all this information to the third party along with any identifying information (names, credit card numbers, addresses) obtained by the site. If a third party cooperates with multiple sites to obtain such information, a profile can still be created.
However, user tracking is to some extent possible even with no cooperation from the user agent whatsoever, for instance by using session identifiers in URLs, a technique already commonly used for innocuous purposes but easily repurposed for user tracking (even retroactively). This information can then be shared with other sites, using visitors' IP addresses and other user-specific data (e.g. user-agent headers and configuration settings) to combine separate sessions into coherent user profiles.
User agents should treat persistently stored data as potentially sensitive; it's quite possible for emails, calendar appointments, health records, or other confidential documents to be stored in this mechanism.
To this end, user agents should ensure that when deleting data, it is promptly deleted from the underlying storage.
Because of the potential for DNS spoofing attacks, one cannot guarantee that a host claiming to be in a certain domain really is from that domain. To mitigate this, pages can use TLS. Pages using TLS can be sure that only the user, software working on behalf of the user, and other pages using TLS that have certificates identifying them as being from the same domain, can access their storage areas.
Different authors sharing one host name, for example users hosting content on the now defunct
geocities.com, all share one local storage object. There is no feature to
restrict the access by pathname. Authors on shared hosts are therefore urged to avoid using
these
features, as it would be trivial for other authors to read the data and overwrite it.
Even if a path-restriction feature was made available, the usual DOM scripting security model would make it trivial to bypass this protection and access the data from any path.
The two primary risks when implementing these persistent storage features are letting hostile sites read information from other domains, and letting hostile sites write information that is then read from other domains.
Letting third-party sites read data that is not supposed to be read from their domain causes information leakage. For example, a user's shopping wishlist on one domain could be used by another domain for targeted advertising; or a user's work-in-progress confidential documents stored by a word-processing site could be examined by the site of a competing company.
Letting third-party sites write data to the persistent storage of other domains can result in information spoofing, which is equally dangerous. For example, a hostile site could add items to a user's wishlist; or a hostile site could set a user's session identifier to a known ID that the hostile site can then use to track the user's actions on the victim site.
Thus, strictly following the origin model described in this specification is important for user security.
This section only describes the rules for resources labeled with an HTML MIME type. Rules for XML resources are discussed in the section below entitled "The XML syntax".
This section only applies to documents, authoring tools, and markup generators. In particular, it does not apply to conformance checkers; conformance checkers must use the requirements given in the next section ("parsing HTML documents").
Documents must consist of the following parts, in the given order:
html element.
The various types of content mentioned above are described in the next few sections.
In addition, there are some restrictions on how character encoding declarations are to be serialized, as discussed in the section on that topic.
ASCII whitespace before the html element, at the
start of
the
html element and
before the
head element, will be
dropped
when the
document is parsed; ASCII
whitespace after the html element
will be parsed as if it were at the end of the body element. Thus, ASCII
whitespace around the document
element
does not round-trip.
It is suggested that newlines be inserted after the DOCTYPE, after any comments that are
before the document element, after the html element's start
tag (if
it is
not omitted), and after any
comments
that
are inside the
html element but
before the
head element.
Many strings in the HTML syntax (e.g. the names of elements and their attributes) are case-insensitive, but only for ASCII upper alphas and ASCII lower alphas. For convenience, in this section this is just referred to as "case-insensitive".
A DOCTYPE is a required preamble.
DOCTYPEs are required for legacy reasons. When omitted, browsers tend to use a different rendering mode that is incompatible with some specifications. Including the DOCTYPE in a document ensures that the browser makes a best-effort attempt at following the relevant specifications.
A DOCTYPE must consist of the following components, in this order:
<!DOCTYPE".
html".
In other words, <!DOCTYPE html>, case-insensitively.
For the purposes of HTML generators that cannot output HTML markup with the short DOCTYPE
"<!DOCTYPE html>", a DOCTYPE legacy string
may be
inserted
into the DOCTYPE (in the position defined above). This string must consist of:
SYSTEM".
about:legacy-compat".
In other words, <!DOCTYPE html SYSTEM "about:legacy-compat"> or
<!DOCTYPE html SYSTEM 'about:legacy-compat'>, case-insensitively except for the
part in single or double quotes.
The DOCTYPE legacy string should not be used unless the document is generated from a system that cannot output the shorter string.
There are six different kinds of elements: void
elements, the
template
element, raw text
elements, escapable
raw
text elements, foreign
elements,
and
normal elements.
area, base, br, col, embed,
hr, img, input, link, meta,
source, track, wbr
template element
template
script, style
textarea,
title
Tags are used to delimit the start and end of elements in the markup. Raw text, escapable raw text, and normal elements have a start tag to indicate where they begin, and an end tag to indicate where they end. The start and end tags of certain normal elements can be omitted, as described below in the section on optional tags. Those that cannot be omitted must not be omitted. Void elements only have a start tag; end tags must not be specified for void elements. Foreign elements must either have a start tag and an end tag, or a start tag that is marked as self-closing, in which case they must not have an end tag.
The contents of the element must be placed between just after the start tag (which might be implied, in certain cases) and just before the end tag (which again, might be implied in certain cases). The exact allowed contents of each individual element depend on the content model of that element, as described earlier in this specification. Elements must not contain content that their content model disallows. In addition to the restrictions placed on the contents by those content models, however, the five types of elements have additional syntactic requirements.
Void elements can't have any contents (since there's no end tag, no content can be put between the start tag and the end tag).
The
template element can have
template contents, but such template contents are not
children of
the
template
element
itself.
Instead, they are stored in a DocumentFragment
associated with a different Document —
without
a browsing context — so
as to avoid the template
contents interfering with the main Document.
The markup for the template
contents of
a template
element
is placed
just after the template
element's start tag and just before template
element's end tag (as with other elements), and may consist of any text, character
references, elements, and comments, but
the text must not contain the character U+003C LESS-THAN SIGN (<) or an ambiguous
ampersand.
Raw text elements can have text, though it has restrictions described below.
Escapable raw text elements can have text and character references, but the text must not contain an ambiguous ampersand. There are also further restrictions described below.
Foreign elements whose start tag is marked as self-closing can't have any contents (since, again, as there's no end tag, no content can be put between the start tag and the end tag). Foreign elements whose start tag is not marked as self-closing can have text, character references, CDATA sections, other elements, and comments, but the text must not contain the character U+003C LESS-THAN SIGN (<) or an ambiguous ampersand.
The HTML syntax does not support namespace declarations, even in foreign elements.
For instance, consider the following HTML fragment:
< p >
< svg >
< metadata >
<!-- this is invalid -->
< cdr:license xmlns:cdr = "https://www.example.com/cdr/metadata" name = "MIT" />
</ metadata >
</ svg >
</ p >
The innermost element, cdr:license, is actually in the SVG namespace, as
the "xmlns:cdr" attribute has no effect (unlike in XML). In fact, as the
comment in the fragment above says, the fragment is actually non-conforming. This is because
SVG 2 does not define any elements called "cdr:license" in
the SVG namespace.
Normal elements can have text, character references, other elements, and comments, but the text must not contain the character U+003C LESS-THAN SIGN (<) or an ambiguous ampersand. Some normal elements also have yet more restrictions on what content they are allowed to hold, beyond the restrictions imposed by the content model and those described in this paragraph. Those restrictions are described below.
Tags contain a tag name, giving the element's name. HTML elements all have names that only use ASCII alphanumerics. In the HTML syntax, tag names, even those for foreign elements, may be written with any mix of lower- and uppercase letters that, when converted to all-lowercase, matches the element's tag name; tag names are case-insensitive.
Start tags must have the following format:
End tags must have the following format:
Attributes for an element are expressed inside the element's start tag.
Attributes have a name and a value. Attribute names must consist of one or more characters other than controls, U+0020 SPACE, U+0022 ("), U+0027 ('), U+003E (>), U+002F (/), U+003D (=), and noncharacters. In the HTML syntax, attribute names, even those for foreign elements, may be written with any mix of ASCII lower and ASCII upper alphas.
Attribute values are a mixture of text and character references, except with the additional restriction that the text cannot contain an ambiguous ampersand.
Attributes can be specified in four different ways:
Just the attribute name. The value is implicitly the empty string.
In the following example, the disabled
attribute
is
given with the empty attribute syntax:
< input disabled >
If an attribute using the empty attribute syntax is to be followed by another attribute, then there must be ASCII whitespace separating the two.
The attribute name, followed by zero or more ASCII whitespace, followed by a single U+003D EQUALS SIGN character, followed by zero or more ASCII whitespace, followed by the attribute value, which, in addition to the requirements given above for attribute values, must not contain any literal ASCII whitespace, any U+0022 QUOTATION MARK characters ("), U+0027 APOSTROPHE characters ('), U+003D EQUALS SIGN characters (=), U+003C LESS-THAN SIGN characters (<), U+003E GREATER-THAN SIGN characters (>), or U+0060 GRAVE ACCENT characters (`), and must not be the empty string.
In the following example, the value
attribute is
given
with the unquoted attribute value syntax:
< input value = yes >
If an attribute using the unquoted attribute syntax is to be followed by another attribute or by the optional U+002F SOLIDUS character (/) allowed in step 6 of the start tag syntax above, then there must be ASCII whitespace separating the two.
The attribute name, followed by zero or more ASCII whitespace, followed by a single U+003D EQUALS SIGN character, followed by zero or more ASCII whitespace, followed by a single U+0027 APOSTROPHE character ('), followed by the attribute value, which, in addition to the requirements given above for attribute values, must not contain any literal U+0027 APOSTROPHE characters ('), and finally followed by a second single U+0027 APOSTROPHE character (').
In the following example, the type
attribute is
given
with the single-quoted attribute value syntax:
< input type = 'checkbox' >
If an attribute using the single-quoted attribute syntax is to be followed by another attribute, then there must be ASCII whitespace separating the two.
The attribute name, followed by zero or more ASCII whitespace, followed by a single U+003D EQUALS SIGN character, followed by zero or more ASCII whitespace, followed by a single U+0022 QUOTATION MARK character ("), followed by the attribute value, which, in addition to the requirements given above for attribute values, must not contain any literal U+0022 QUOTATION MARK characters ("), and finally followed by a second single U+0022 QUOTATION MARK character (").
In the following example, the name attribute is
given
with
the double-quoted attribute value syntax:
< input name = "be evil" >
If an attribute using the double-quoted attribute syntax is to be followed by another attribute, then there must be ASCII whitespace separating the two.
There must never be two or more attributes on the same start tag whose names are an ASCII case-insensitive match for each other.
When a foreign element has one of the namespaced attributes given by the local name and namespace of the first and second cells of a row from the following table, it must be written using the name given by the third cell from the same row.
| Local name | Namespace | Attribute name |
|---|---|---|
actuate
| XLink namespace | xlink:actuate
|
arcrole
| XLink namespace | xlink:arcrole
|
href
| XLink namespace | xlink:href
|
role
| XLink namespace | xlink:role
|
show
| XLink namespace | xlink:show
|
title
| XLink namespace | xlink:title
|
type
| XLink namespace | xlink:type
|
lang
| XML namespace | xml:lang
|
space
| XML namespace | xml:space
|
xmlns
| XMLNS namespace | xmlns
|
xlink
| XMLNS namespace | xmlns:xlink
|
No other namespaced attribute can be expressed in the HTML syntax.
Whether the attributes in the table above are conforming or not is defined by other specifications (e.g. SVG 2 and MathML); this section only describes the syntax rules if the attributes are serialized using the HTML syntax.
Certain tags can be omitted.
Omitting an element's start
tag in the
situations described below does not mean the element is not present; it is implied, but it is
still there. For example, an HTML document always has a root html element, even if
the string <html> doesn't appear anywhere in the markup.
An html element's
start tag may be omitted
if the first thing inside the html element is not
a comment.
For example, in the following case it's ok to remove the "<html>"
tag:
<!DOCTYPE HTML>
< html >
< head >
< title > Hello</ title >
</ head >
< body >
< p > Welcome to this example.</ p >
</ body >
</ html >
Doing so would make the document look like this:
<!DOCTYPE HTML>
< head >
< title > Hello</ title >
</ head >
< body >
< p > Welcome to this example.</ p >
</ body >
</ html >
This has the exact same DOM. In particular, note that whitespace around the document element is ignored by the parser. The following example would also have the exact same DOM:
<!DOCTYPE HTML> < head >
< title > Hello</ title >
</ head >
< body >
< p > Welcome to this example.</ p >
</ body >
</ html >
However, in the following example, removing the start tag moves the comment to before the
html element:
<!DOCTYPE HTML>
< html >
<!-- where is this comment in the DOM? -->
< head >
< title > Hello</ title >
</ head >
< body >
< p > Welcome to this example.</ p >
</ body >
</ html >
With the tag removed, the document actually turns into the same as this:
<!DOCTYPE HTML>
<!-- where is this comment in the DOM? -->
< html >
< head >
< title > Hello</ title >
</ head >
< body >
< p > Welcome to this example.</ p >
</ body >
</ html >
This is why the tag can only be removed if it is not followed by a comment: removing the tag when there is a comment there changes the document's resulting parse tree. Of course, if the position of the comment does not matter, then the tag can be omitted, as if the comment had been moved to before the start tag in the first place.
An html element's
end tag may be omitted if
the html element
is not
immediately followed by a comment.
A head element's start tag may be omitted if
the element is empty, or if the first thing inside the head element is an
element.
A head element's
end tag may be omitted if
the head element
is not
immediately followed by ASCII
whitespace
or a
comment.
A body element's start tag may be omitted
if the element is empty, or if the first thing inside the body element is not
ASCII whitespace or a comment, except if the
first thing inside the body
element is a meta,
noscript,
link, script, style, or template
element.
A body element's
end tag may be omitted if the
body element is
not
immediately
followed by a comment.
Note that in the example above, the head element
start and
end
tags, and the
body element
start
tag, can't
be omitted, because they are surrounded by
whitespace:
<!DOCTYPE HTML>
< html >
< head >
< title > Hello</ title >
</ head >
< body >
< p > Welcome to this example.</ p >
</ body >
</ html >
(The body and
html element
end tags
could be
omitted without
trouble; any spaces after those get parsed into the body element
anyway.)
Usually, however, whitespace isn't an issue. If we first remove the whitespace we don't care about:
<!DOCTYPE HTML> < html >< head >< title > Hello</ title ></ head >< body >< p > Welcome to this example.</ p ></ body ></ html >
Then we can omit a number of tags without affecting the DOM:
<!DOCTYPE HTML> < title > Hello</ title >< p > Welcome to this example.</ p >
At that point, we can also add some whitespace back:
<!DOCTYPE HTML>
< title > Hello</ title >
< p > Welcome to this example.</ p >
This would be equivalent to this document, with the omitted tags shown in their
parser-implied positions; the only whitespace text node that results from this is the
newline at
the end of the head
element:
<!DOCTYPE HTML>
< html >< head > < title > Hello</ title >
</ head >< body > < p > Welcome to this example.</ p > </ body ></ html >
An li element's end tag may be omitted if the
li element is
immediately
followed by
another li element or
if
there is
no more content in the parent element.
A dt element's end tag may be omitted if the
dt element is
immediately
followed by
another dt element or
a
dd element.
A dd element's end tag may be omitted if the
dd element is
immediately
followed by
another dd element or
a
dt element, or if
there is no
more
content in the parent element.
A p element's end tag may be omitted if the
p element is
immediately
followed by an
address,
article,
aside, blockquote,
details,
div,
dl, fieldset,
figcaption,
figure,
footer, form, h1,
h2,
h3,
h4,
h5,
h6,
header, hgroup,
hr, main, menu, nav, ol,
p, pre, search, section, table,
or ul element, or if
there is
no more
content in the parent element and the parent
element is an HTML element that is not
an
a,
audio, del, ins, map, noscript,
or video element,
or an
autonomous custom
element.
We can thus simplify the earlier example further:
<!DOCTYPE HTML> < title > Hello</ title >< p > Welcome to this example.
An rt element's end tag may be omitted if the
rt element is
immediately
followed by
an rt or rp element,
or if there is no more content in the parent element.
An rp element's end tag may be omitted if the
rp element is
immediately
followed by
an rt or rp element,
or if there is no more content in the parent element.
An optgroup
element's end tag may be omitted
if the optgroup
element
is
immediately followed by another optgroup
element,
if it is
immediately followed by an
hr element, or if
there is no
more
content in the parent
element.
An option
element's end tag may be omitted
if
the option
element is
immediately followed by another option element,
if
it is immediately followed by an optgroup
element,
if it is
immediately followed by
an hr element, or if
there is
no more
content in the parent element.
A colgroup
element's
start tag may be
omitted if the first thing inside the colgroup
element is
a col element,
and if the element is not immediately preceded by another colgroup
element
whose
end tag has been omitted. (It
can't be
omitted if
the element
is empty.)
A colgroup
element's end tag may be omitted
if the colgroup
element
is not immediately followed by ASCII
whitespace
or a comment.
A caption
element's end tag may be omitted
if
the caption
element
is not
immediately followed by ASCII
whitespace
or a
comment.
A thead element's
end tag may be omitted if
the thead
element is
immediately followed by a tbody
or
tfoot element.
A tbody
element's start tag may be
omitted
if the first thing inside the tbody element is
a tr element, and if
the
element is not immediately preceded by a tbody, thead, or
tfoot element
whose end tag has been omitted.
(It
can't be omitted if the element is empty.)
A tbody
element's end tag may be omitted
if
the tbody
element is
immediately followed by a tbody
or
tfoot element,
or if
there is
no more content in the parent element.
A tfoot
element's end tag may be omitted
if
there is no more content in the parent element.
A tr element's end tag may be omitted if the
tr element is
immediately
followed by
another tr element,
or if
there is
no more content in the parent element.
A td element's end tag may be omitted if the
td element is
immediately
followed by
a td or th element,
or if there is no more content in the parent element.
A th element's end tag may be omitted if the
th element is
immediately
followed by
a td or th element,
or if there is no more content in the parent element.
The ability to omit all these table-related tags makes table markup much terser.
Take this example:
< table >
< caption > 37547 TEE Electric Powered Rail Car Train Functions (Abbreviated)</ caption >
< colgroup >< col >< col >< col ></ colgroup >
< thead >
< tr >
< th > Function</ th >
< th > Control Unit</ th >
< th > Central Station</ th >
</ tr >
</ thead >
< tbody >
< tr >
< td > Headlights</ td >
< td > ✔</ td >
< td > ✔</ td >
</ tr >
< tr >
< td > Interior Lights</ td >
< td > ✔</ td >
< td > ✔</ td >
</ tr >
< tr >
< td > Electric locomotive operating sounds</ td >
< td > ✔</ td >
< td > ✔</ td >
</ tr >
< tr >
< td > Engineer's cab lighting</ td >
< td ></ td >
< td > ✔</ td >
</ tr >
< tr >
< td > Station Announcements - Swiss</ td >
< td ></ td >
< td > ✔</ td >
</ tr >
</ tbody >
</ table >
The exact same table, modulo some whitespace differences, could be marked up as follows:
< table >
< caption > 37547 TEE Electric Powered Rail Car Train Functions (Abbreviated)
< colgroup >< col >< col >< col >
< thead >
< tr >
< th > Function
< th > Control Unit
< th > Central Station
< tbody >
< tr >
< td > Headlights
< td > ✔
< td > ✔
< tr >
< td > Interior Lights
< td > ✔
< td > ✔
< tr >
< td > Electric locomotive operating sounds
< td > ✔
< td > ✔
< tr >
< td > Engineer's cab lighting
< td >
< td > ✔
< tr >
< td > Station Announcements - Swiss
< td >
< td > ✔
</ table >
Since the cells take up much less room this way, this can be made even terser by having each row on one line:
< table >
< caption > 37547 TEE Electric Powered Rail Car Train Functions (Abbreviated)
< colgroup >< col >< col >< col >
< thead >
< tr > < th > Function < th > Control Unit < th > Central Station
< tbody >
< tr > < td > Headlights < td > ✔ < td > ✔
< tr > < td > Interior Lights < td > ✔ < td > ✔
< tr > < td > Electric locomotive operating sounds < td > ✔ < td > ✔
< tr > < td > Engineer's cab lighting < td > < td > ✔
< tr > < td > Station Announcements - Swiss < td > < td > ✔
</ table >
The only differences between these tables, at the DOM level, is with the precise position of the (in any case semantically-neutral) whitespace.
However, a start tag must never be omitted if it has any attributes.
Returning to the earlier example with all the whitespace removed and then all the optional tags removed:
<!DOCTYPE HTML> < title > Hello</ title >< p > Welcome to this example.
If the body
element in
this
example had to have a class
attribute and
the
html element
had to
have a
lang attribute, the markup
would have
to
become:
<!DOCTYPE HTML> < html lang = "en" >< title > Hello</ title >< body class = "demo" >< p > Welcome to this example.
This section assumes that the document is conforming, in particular, that there are no content model violations. Omitting tags in the fashion described in this section in a document that does not conform to the content models described in this specification is likely to result in unexpected DOM differences (this is, in part, what the content models are designed to avoid).
For historical reasons, certain elements have extra restrictions beyond even the restrictions given by their content model.
A table
element
must not
contain tr
elements,
even though
these
elements are technically allowed inside table
elements
according
to the content
models described in this specification. (If a tr element is
put inside
a
table in
the
markup, it
will in fact imply a tbody
start tag before
it.)
A single newline may be
placed
immediately
after the start tag of
pre and textarea
elements.
This does not affect the processing of the element. The otherwise optional newline must be
included if the element's
contents
themselves start with a newline
(because
otherwise the
leading newline in the contents would be treated like the optional newline, and ignored).
The text in raw
text and escapable
raw
text
elements must not contain any occurrences of the string "</"
(U+003C LESS-THAN SIGN, U+002F SOLIDUS) followed by characters that case-insensitively match the
tag name of the element followed by one of U+0009 CHARACTER TABULATION (tab), U+000A LINE FEED
(LF), U+000C FORM FEED (FF), U+000D CARRIAGE RETURN (CR), U+0020 SPACE, U+003E GREATER-THAN SIGN
(>), or U+002F SOLIDUS (/).
Text is allowed inside elements, attribute values, and comments. Extra constraints are placed on what is and what is not allowed in text based on where the text is to be put, as described in the other sections.
Newlines in HTML may be represented either as U+000D CARRIAGE RETURN (CR) characters, U+000A LINE FEED (LF) characters, or pairs of U+000D CARRIAGE RETURN (CR), U+000A LINE FEED (LF) characters in that order.
Where character references are allowed, a character reference of a U+000A LINE FEED (LF) character (but not a U+000D CARRIAGE RETURN (CR) character) also represents a newline.
In certain cases described in other sections, text may be mixed with character references. These can be used to escape characters that couldn't otherwise legally be included in text.
Character references must start with a U+0026 AMPERSAND character (&). Following this, there are three possible kinds of character references:
The numeric character reference forms described above are allowed to reference any code point excluding U+000D CR, noncharacters, and controls other than ASCII whitespace.
An ambiguous ampersand is a U+0026 AMPERSAND character (&) that is followed by one or more ASCII alphanumerics, followed by a U+003B SEMICOLON character (;), where these characters do not match any of the names given in the named character references section.
CDATA sections must consist of the following components, in this order:
<![CDATA[".
]]>".
]]>".
CDATA sections can only be used in foreign content (MathML or SVG). In this example, a CDATA
section is used to escape the contents of a MathML
ms element:
< p > You can add a string to a number, but this stringifies the number:</ p >
< math >
< ms > <![CDATA[x<y]]> </ ms >
< mo > +</ mo >
< mn > 3</ mn >
< mo > =</ mo >
< ms > <![CDATA[x<y3]]> </ ms >
</ math >
Comments must have the following format:
<!--".
>", nor start with the string
"->", nor contain the strings "<!--", "-->", or
"--!>", nor end with the string "<!-".
-->".
The text is allowed to end with the
string
"<!", as in <!--My favorite operators are > and
<!-->.
This section only applies to user agents, data mining tools, and conformance checkers.
The rules for parsing XML documents into DOM trees are covered by the next section, entitled "The XML syntax".
User agents must use the parsing rules described in this section to generate the DOM trees from
text/html resources. Together, these
rules
define what
is referred to as the
HTML parser.
While the HTML syntax described in this specification bears a close resemblance to SGML and XML, it is a separate language with its own parsing rules.
Some earlier versions of HTML (in particular from HTML2 to HTML4) were based on SGML and used SGML parsing rules. However, few (if any) web browsers ever implemented true SGML parsing for HTML documents; the only user agents to strictly handle HTML as an SGML application have historically been validators. The resulting confusion — with validators claiming documents to have one representation while widely deployed web browsers interoperably implemented a different representation — has wasted decades of productivity. This version of HTML thus returns to a non-SGML basis.
Authors interested in using SGML tools in their authoring pipeline are encouraged to use XML tools and the XML serialization of HTML.
For the purposes of conformance checkers, if a resource is determined to be in the HTML syntax, then it is an HTML document.
As stated in the terminology
section,
references to element types that do not
explicitly
specify a
namespace always refer to elements in the HTML
namespace. For
example, if the spec
talks about "a menu
element",
then that
is an element with the local name "menu", the namespace
"http://www.w3.org/1999/xhtml", and
the interface HTMLMenuElement.
Where
possible, references to such elements are
hyperlinked to their definition.
The input to the HTML parsing process consists of a stream of code
points, which is passed through a tokenization stage followed by a tree
construction stage. The output is a Document object.
Implementations that do not support scripting do not
have to actually create a DOM Document object,
but the
DOM tree
in such cases is
still used as the model for the rest of the specification.
In the common case, the data handled by the tokenization stage comes from the network, but
it
can also
come
from script running in the user
agent, e.g. using the document.write()
API.
There is only one set of states for the tokenizer stage and the tree construction stage, but the tree construction stage is reentrant, meaning that while the tree construction stage is handling one token, the tokenizer might be resumed, causing further tokens to be emitted and processed before the first token's processing is complete.
In the following example, the tree construction stage will be called upon to handle a "p" start tag token while handling the "script" end tag token:
...
< script >
document. write( '<p>' );
</ script >
...
To handle these cases, parsers have a script nesting level, which must be initially set to zero, and a parser pause flag, which must be initially set to false.
This specification defines the parsing rules for HTML documents, whether they are syntactically correct or not. Certain points in the parsing algorithm are said to be parse errors. The error handling for parse errors is well-defined (that's the processing rules described throughout this specification), but user agents, while parsing an HTML document, may abort the parser at the first parse error that they encounter for which they do not wish to apply the rules described in this specification.
Conformance checkers must report at least one parse error condition to the user if one or more parse error conditions exist in the document and must not report parse error conditions if none exist in the document. Conformance checkers may report more than one parse error condition if more than one parse error condition exists in the document.
Parse errors are only errors with the syntax of HTML. In addition to checking for parse errors, conformance checkers will also verify that the document obeys all the other conformance requirements described in this specification.
Some parse errors have dedicated codes outlined in the table below that should be used by conformance checkers in reports.
Error descriptions in the table below are non-normative.
| Code | Description |
|---|---|
| abrupt-closing-of-empty-comment |
This error occurs if the parser encounters an empty comment that is abruptly closed by a
U+003E (>)
code
point (i.e., |
| abrupt-doctype-public-identifier |
This error occurs if the parser encounters a U+003E (>) code
point in
the
DOCTYPE public
identifier
(e.g.,
|
| abrupt-doctype-system-identifier |
This error occurs if the parser encounters a U+003E (>) code
point in
the
DOCTYPE system
identifier
(e.g.,
|
| absence-of-digits-in-numeric-character-reference |
This error occurs if the parser encounters a numeric character reference that doesn't contain
any
digits
(e.g., |
| cdata-in-html-content |
This error occurs if the parser encounters a CDATA
section outside of foreign content (SVG or MathML). The parser treats
such CDATA
sections (including leading " |
| character-reference-outside-unicode-range |
This error occurs if the parser encounters a numeric character reference that references a code point that is greater than the valid Unicode range. The parser resolves such a character reference to a U+FFFD REPLACEMENT CHARACTER. |
| control-character-in-input-stream |
This error occurs if the input stream contains a control code point that is not ASCII whitespace or U+0000 NULL. Such code points are parsed as-is and usually, where parsing rules don't apply any additional restrictions, make their way into the DOM. |
| control-character-reference |
This error occurs if the parser encounters a numeric character reference that references a control code point that is not ASCII whitespace or is a U+000D CARRIAGE RETURN. The parser resolves such character references as-is except C1 control references that are replaced according to the numeric character reference end state. |
| duplicate-attribute |
This error occurs if the parser encounters an attribute in a tag that already has an attribute with the same name. The parser ignores all such duplicate occurrences of the attribute. |
| end-tag-with-attributes |
This error occurs if the parser encounters an end tag with attributes. Attributes in end tags are ignored and do not make their way into the DOM. |
| end-tag-with-trailing-solidus |
This error occurs if the parser encounters an end
tag that has a U+002F (/) code
point
right before the closing U+003E (>)
code point (e.g., |
| eof-before-tag-name |
This error occurs if the parser encounters the end of the input stream
where a tag name is expected. In this case the parser treats the beginning of a
start tag (i.e.,
|
| eof-in-cdata |
This error occurs if the parser encounters the end of the input stream in a CDATA section. The parser treats such CDATA sections as if they are closed immediately before the end of the input stream. |
| eof-in-comment |
This error occurs if the parser encounters the end of the input stream in a comment. The parser treats such comments as if they are closed immediately before the end of the input stream. |
| eof-in-doctype |
This error occurs if the parser encounters the end of the input stream in a DOCTYPE. In such a
case,
if the
DOCTYPE is correctly placed as a
document preamble, the parser sets the |
| eof-in-script-html-comment-like-text |
This error occurs if the parser encounters the end of the input stream in text
that resembles an HTML
comment
inside
Syntactic structures that resemble HTML comments in |
| eof-in-tag |
This error occurs if the parser encounters the end of the input stream in a
start tag or an
end
tag (e.g., |
| incorrectly-closed-comment |
This error occurs if the parser encounters a comment that is closed by the
" |
| incorrectly-opened-comment |
This error occurs if the parser encounters the " One possible cause of this error is using an XML markup declaration
(e.g.,
|
| invalid-character-sequence-after-doctype-name |
This error occurs if the parser encounters any code
point
sequence other
than " |
| invalid-first-character-of-tag-name |
This error occurs if the parser encounters a code point that is not an ASCII alpha where first code point of a start tag name or an end tag name is expected. If a start tag was expected such code point and a preceding U+003C (<) is treated as text content, and all content that follows is treated as markup. Whereas, if an end tag was expected, such code point and all content that follows up to a U+003E (>) code point (if present) or to the end of the input stream is treated as a comment. For example, consider the following markup:
This will be parsed into: While the first code point of a tag name is limited to an ASCII alpha, a wide range of code points (including ASCII digits) is allowed in subsequent positions. |
| missing-attribute-value |
This error occurs if the parser encounters a U+003E (>) code
point
where an
attribute
value is
expected
(e.g., |
| missing-doctype-name |
This error occurs if the parser encounters a DOCTYPE that is missing a name (e.g.,
|
| missing-doctype-public-identifier |
This error occurs if the parser encounters a U+003E (>) code
point
where
start of the DOCTYPE public
identifier is expected (e.g.,
|
| missing-doctype-system-identifier |
This error occurs if the parser encounters a U+003E (>) code
point
where
start of the DOCTYPE system
identifier is expected (e.g.,
|
| missing-end-tag-name |
This error occurs if the parser encounters a U+003E (>) code
point
where an
end tag name is
expected,
i.e.,
|
| missing-quote-before-doctype-public-identifier |
This error occurs if the parser encounters the DOCTYPE public identifier that is not
preceded
by a
quote (e.g.,
|
| missing-quote-before-doctype-system-identifier |
This error occurs if the parser encounters the DOCTYPE system identifier that is not
preceded
by a
quote (e.g.,
|
| missing-semicolon-after-character-reference |
This error occurs if the parser encounters a character reference that is not terminated by a U+003B (;) code point. Usually the parser behaves as if character reference is terminated by the U+003B (;) code point; however, there are some ambiguous cases in which the parser includes subsequent code points in the character reference. For example, |
| missing-whitespace-after-doctype-public-keyword |
This error occurs if the parser encounters a DOCTYPE whose " |
| missing-whitespace-after-doctype-system-keyword |
This error occurs if the parser encounters a DOCTYPE whose " |
| missing-whitespace-before-doctype-name |
This error occurs if the parser encounters a DOCTYPE whose " |
| missing-whitespace-between-attributes |
This error occurs if the parser encounters attributes that are not separated by
ASCII
whitespace (e.g., |
| missing-whitespace-between-doctype-public-and-system-identifiers |
This error occurs if the parser encounters a DOCTYPE whose public and system identifiers are not separated by ASCII whitespace. In this case the parser behaves as if ASCII whitespace is present. |
| nested-comment |
This error occurs if the parser encounters a nested comment (e.g., |
| noncharacter-character-reference |
This error occurs if the parser encounters a numeric character reference that references a noncharacter. The parser resolves such character references as-is. |
| noncharacter-in-input-stream |
This error occurs if the input stream contains a noncharacter. Such code points are parsed as-is and usually, where parsing rules don't apply any additional restrictions, make their way into the DOM. |
| non-void-html-element-start-tag-with-trailing-solidus |
This error occurs if the parser encounters a start tag for an element that is not in the list of void elements or is not a part of foreign content (i.e., not an SVG or MathML element) that has a U+002F (/) code point right before the closing U+003E (>) code point. The parser behaves as if the U+002F (/) is not present. For example, consider the following markup:
This will be parsed into: The trailing U+002F (/) in a start tag name can be used only in foreign content to specify self-closing tags. (Self-closing tags don't exist in HTML.) It is also allowed for void elements, but doesn't have any effect in this case. |
| null-character-reference |
This error occurs if the parser encounters a numeric character reference that references a U+0000 NULL code point. The parser resolves such character references to a U+FFFD REPLACEMENT CHARACTER. |
| surrogate-character-reference |
This error occurs if the parser encounters a numeric character reference that references a surrogate. The parser resolves such character references to a U+FFFD REPLACEMENT CHARACTER. |
| surrogate-in-input-stream |
This error occurs if the input stream contains a surrogate. Such code points are parsed as-is and usually, where parsing rules don't apply any additional restrictions, make their way into the DOM. Surrogates can only find their way into the input stream via script
APIs such
as |
| unexpected-character-after-doctype-system-identifier |
This error occurs if the parser encounters any code points other than ASCII whitespace or closing U+003E (>) after the DOCTYPE system identifier. The parser ignores these code points. |
| unexpected-character-in-attribute-name |
This error occurs if the parser encounters a U+0022 ("), U+0027 ('), or U+003C (<) code point in an attribute name. The parser includes such code points in the attribute name. Code points that trigger this error are usually a part of another syntactic construct and can be a sign of a typo around the attribute name. For example, consider the following markup:
Due to a forgotten U+003E (>) code point after As another example of this error, consider the following markup:
Due to a forgotten U+003D (=) code point between an attribute name and value
the
parser
treats this markup as a |
| unexpected-character-in-unquoted-attribute-value |
This error occurs if the parser encounters a U+0022 ("), U+0027 ('), U+003C (<), U+003D (=), or U+0060 (`) code point in an unquoted attribute value. The parser includes such code points in the attribute value. Code points that trigger this error are usually a part of another syntactic construct and can be a sign of a typo around the attribute value. U+0060 (`) is in the list of code points that trigger this error because certain legacy user agents treat it as a quote. For example, consider the following markup:
Due to a misplaced U+0027 (') code point the parser sets the value of the
" |
| unexpected-equals-sign-before-attribute-name |
This error occurs if the parser encounters a U+003D (=) code point before an attribute name. In this case the parser treats U+003D (=) as the first code point of the attribute name. The common reason for this error is a forgotten attribute name. For example, consider the following markup:
Due to a forgotten attribute name the parser treats this markup as a |
| unexpected-null-character |
This error occurs if the parser encounters a U+0000 NULL code point in the input stream in certain positions. In general, such code points are either ignored or, for security reasons, replaced with a U+FFFD REPLACEMENT CHARACTER. |
| unexpected-question-mark-instead-of-tag-name |
This error occurs if the parser encounters a U+003F (?) code point where first code point of a start tag name is expected. The U+003F (?) and all content that follows up to a U+003E (>) code point (if present) or to the end of the input stream is treated as a comment. For example, consider the following markup:
This will be parsed into: The common reason for this error is an XML processing instruction
(e.g.,
|
| unexpected-solidus-in-tag |
This error occurs if the parser encounters a U+002F (/) code
point
that is
not a part of a quoted attribute value and not
immediately followed by a U+003E (>) code point in a tag (e.g., |
| unknown-named-character-reference |
This error occurs if the parser encounters an ambiguous ampersand. In this case the parser doesn't resolve the character reference. |
The stream of code points that comprises the input to the tokenization stage will be initially seen by the user agent as a stream of bytes (typically coming over the network or from the local file system). The bytes encode the actual characters according to a particular character encoding, which the user agent uses to decode the bytes into characters.
For XML documents, the algorithm user agents are required to use to determine the character encoding is given by XML. This section does not apply to XML documents. [XML]
Usually, the encoding sniffing algorithm defined below is used to determine the character encoding.
Given a character encoding, the bytes in the input byte stream must be converted to characters for the tokenizer's input stream, by passing the input byte stream and character encoding to decode.
A leading Byte Order Mark (BOM) causes the character encoding argument to be ignored and will itself be skipped.
Bytes or sequences of bytes in the original byte stream that did not conform to the Encoding standard (e.g. invalid UTF-8 byte sequences in a UTF-8 input byte stream) are errors that conformance checkers are expected to report. [ENCODING]
The decoder algorithms describe how to handle invalid input; for security reasons, it is imperative that those rules be followed precisely. Differences in how invalid byte sequences are handled can result in, amongst other problems, script injection vulnerabilities ("XSS").
When the HTML parser is decoding an input byte stream, it uses a character encoding and a confidence. The confidence is either tentative, certain, or irrelevant. The encoding used, and whether the confidence in that encoding is tentative or certain, is used during the parsing to determine whether to change the encoding. If no encoding is necessary, e.g. because the parser is operating on a Unicode stream and doesn't have to use a character encoding at all, then the confidence is irrelevant.
Some algorithms feed the parser by directly adding characters to the input stream rather than adding bytes to the input byte stream.
When the HTML parser is to operate on an input byte stream that has a known definite encoding, then the character encoding is that encoding and the confidence is certain.
In some cases, it might be impractical to unambiguously determine the encoding before parsing the document. Because of this, this specification provides for a two-pass mechanism with an optional pre-scan. Implementations are allowed, as described below, to apply a simplified parsing algorithm to whatever bytes they have available before beginning to parse the document. Then, the real parser is started, using a tentative encoding derived from this pre-parse and other out-of-band metadata. If, while the document is being loaded, the user agent discovers a character encoding declaration that conflicts with this information, then the parser can get reinvoked to perform a parse of the document with the real encoding.
User agents must use the following algorithm, called the encoding sniffing algorithm, to determine the character encoding to use when decoding a document in the first pass. This algorithm takes as input any out-of-band metadata available to the user agent (e.g. the Content-Type metadata of the document) and all the bytes available so far, and returns a character encoding and a confidence that is either tentative or certain.
If the result of BOM sniffing is an encoding, return that encoding with confidence certain.
Although the decode algorithm will itself change the encoding to use based on the presence of a byte order mark, this algorithm sniffs the BOM as well in order to set the correct document's character encoding and confidence.
If the user has explicitly instructed the user agent to override the document's character encoding with a specific encoding, optionally return that encoding with the confidence certain.
Typically, user agents remember such user requests across sessions, and in
some
cases apply them to documents in iframes
as well.
The user agent may wait for more bytes of the resource to be available, either in this step or at any later step in this algorithm. For instance, a user agent might wait 500ms or 1024 bytes, whichever came first. In general preparsing the source to find the encoding improves performance, as it reduces the need to throw away the data structures used when parsing upon finding the encoding information. However, if the user agent delays too long to obtain data to determine the encoding, then the cost of the delay could outweigh any performance improvements from the preparse.
The authoring conformance requirements for character encoding declarations limit them to only appearing in the first 1024 bytes. User agents are therefore encouraged to use the prescan algorithm below (as invoked by these steps) on the first 1024 bytes, but not to stall beyond that.
If the transport layer specifies a character encoding, and it is supported, return that encoding with the confidence certain.
Optionally prescan the byte stream to determine its encoding, with the end condition being when the user agent decides that scanning further bytes would not be efficient. User agents are encouraged to only prescan the first 1024 bytes. User agents may decide that scanning any bytes is not efficient, in which case these substeps are entirely skipped.
The aforementioned algorithm returns either a character encoding or failure. If it returns a character encoding, then return the same encoding, with confidence tentative.
If the HTML
parser for
which
this algorithm is being run is associated with a
Document
d
whose container
document is non-null, then:
Let parentDocument be d's container document.
If parentDocument's origin is same origin with d's origin and parentDocument's character encoding is not UTF-16BE/LE, then return parentDocument's character encoding, with the confidence tentative.
Otherwise, if the user agent has information on the likely encoding for this page, e.g. based on the encoding of the page when it was last visited, then return that encoding, with the confidence tentative.
The user agent may attempt to autodetect the character encoding from applying frequency analysis or other algorithms to the data stream. Such algorithms may use information about the resource other than the resource's contents, including the address of the resource. If autodetection succeeds in determining a character encoding, and that encoding is a supported encoding, then return that encoding, with the confidence tentative. [UNIVCHARDET]
User agents are generally discouraged from attempting to autodetect encodings for resources obtained over the network, since doing so involves inherently non-interoperable heuristics. Attempting to detect encodings based on an HTML document's preamble is especially tricky since HTML markup typically uses only ASCII characters, and HTML documents tend to begin with a lot of markup rather than with text content.
The UTF-8 encoding has a highly detectable bit pattern. Files from the local file system that contain bytes with values greater than 0x7F which match the UTF-8 pattern are very likely to be UTF-8, while documents with byte sequences that do not match it are very likely not. When a user agent can examine the whole file, rather than just the preamble, detecting for UTF-8 specifically can be especially effective. [PPUTF8] [UTF8DET]
Otherwise, return an implementation-defined or user-specified default character encoding, with the confidence tentative.
In controlled environments or in environments where the encoding of documents can be
prescribed (for example, for user agents intended for dedicated use in new networks),
the
comprehensive UTF-8 encoding is suggested.
In other environments, the default encoding is typically dependent on the user's locale (an approximation of the languages, and thus often encodings, of the pages that the user is likely to frequent). The following table gives suggested defaults based on the user's locale, for compatibility with legacy content. Locales are identified by BCP 47 language tags. [BCP47] [ENCODING]
| Locale language | Suggested default encoding | |
|---|---|---|
| ar | Arabic | windows-1256 |
| az | Azeri | windows-1254 |
| ba | Bashkir | windows-1251 |
| be | Belarusian | windows-1251 |
| bg | Bulgarian | windows-1251 |
| cs | Czech | windows-1250 |
| el | Greek | ISO-8859-7 |
| et | Estonian | windows-1257 |
| fa | Persian | windows-1256 |
| he | Hebrew | windows-1255 |
| hr | Croatian | windows-1250 |
| hu | Hungarian | ISO-8859-2 |
| ja | Japanese | Shift_JIS |
| kk | Kazakh | windows-1251 |
| ko | Korean | EUC-KR |
| ku | Kurdish | windows-1254 |
| ky | Kyrgyz | windows-1251 |
| lt | Lithuanian | windows-1257 |
| lv | Latvian | windows-1257 |
| mk | Macedonian | windows-1251 |
| pl | Polish | ISO-8859-2 |
| ru | Russian | windows-1251 |
| sah | Yakut | windows-1251 |
| sk | Slovak | windows-1250 |
| sl | Slovenian | ISO-8859-2 |
| sr | Serbian | windows-1251 |
| tg | Tajik | windows-1251 |
| th | Thai | windows-874 |
| tr | Turkish | windows-1254 |
| tt | Tatar | windows-1251 |
| uk | Ukrainian | windows-1251 |
| vi | Vietnamese | windows-1258 |
| zh-Hans, zh-CN, zh-SG | Chinese, Simplified | GBK |
| zh-Hant, zh-HK, zh-MO, zh-TW | Chinese, Traditional | Big5 |
| All other locales | windows-1252 | |
The contents of this table are derived from the intersection of Windows, Chrome, and Firefox defaults.
The document's character encoding must immediately be set to the value returned from this algorithm, at the same time as the user agent uses the returned value to select the decoder to use for the input byte stream.
When an algorithm requires a user agent to prescan a byte stream to determine its encoding, given some defined end condition, then it must run the following steps. If at any point during these steps (including during instances of the get an attribute algorithm invoked by this one) the user agent either runs out of bytes (meaning the position pointer created in the first step below goes beyond the end of the byte stream obtained so far) or reaches its end condition, then abort the prescan a byte stream to determine its encoding algorithm and return the result get an XML encoding applied to the same bytes that the prescan a byte stream to determine its encoding algorithm was applied to. Otherwise, these steps will return a character encoding.
Let fallback encoding be null.
Let position be a pointer to a byte in the input byte stream, initially pointing at the first byte.
Prescan for UTF-16 XML declarations: If position points to:
Return UTF-16LE.
Return UTF-16BE.
For historical reasons, the prefix is two bytes longer than in Appendix F of XML and the encoding name is not checked.
Loop: If position points to:
<!--`)
Advance the position pointer so that it points at the first 0x3E byte which is preceded by two 0x2D bytes (i.e. at the end of an ASCII '-->' sequence) and comes after the 0x3C byte that was found. (The two 0x2D bytes can be the same as those in the '<!--' sequence.)
Advance the position pointer so that it points at the next 0x09, 0x0A, 0x0C, 0x0D, 0x20, or 0x2F byte (the one in sequence of characters matched above).
Let attribute list be an empty list of strings.
Let got pragma be false.
Let need pragma be null.
Let charset be the null value (which, for the purposes of this algorithm, is distinct from an unrecognized encoding or the empty string).
Attributes: Get an attribute and its value. If no attribute was sniffed, then jump to the processing step below.
If the attribute's name is already in attribute list, then return to the step labeled attributes.
Add the attribute's name to attribute list.
Run the appropriate step from the following list, if one applies:
http-equiv"
If the attribute's value is "content-type", then set
got
pragma to true.
content"
Apply the algorithm
for extracting a character encoding from a
meta element, giving the attribute's value
as the
string to
parse. If a
character encoding is returned, and if charset is
still set
to null,
let charset be the encoding returned, and set
need
pragma to true.
charset"
Let charset be the result of getting an encoding from the attribute's value, and set need pragma to false.
Return to the step labeled attributes.
Processing: If need pragma is null, then jump to the step below labeled next byte.
If need pragma is true but got pragma is false, then jump to the step below labeled next byte.
If charset is failure, then jump to the step below labeled next byte.
If charset is UTF-16BE/LE, then set charset to UTF-8.
If charset is x-user-defined, then set charset to windows-1252.
Return charset.
Advance the position pointer so that it points at the next 0x09 (HT), 0x0A (LF), 0x0C (FF), 0x0D (CR), 0x20 (SP), or 0x3E (>) byte.
Repeatedly get an attribute until no further attributes can be found, then jump to the step below labeled next byte.
<!`)
</`)
<?`)
Advance the position pointer so that it points at the first 0x3E byte (>) that comes after the 0x3C byte that was found.
Do nothing with that byte.
When the prescan a byte stream to determine its encoding algorithm says to get an attribute, it means doing this:
If the byte at position is one of 0x09 (HT), 0x0A (LF), 0x0C (FF), 0x0D (CR), 0x20 (SP), or 0x2F (/) then advance position to the next byte and redo this step.
If the byte at position is 0x3E (>), then abort the get an attribute algorithm. There isn't one.
Otherwise, the byte at position is the start of the attribute name. Let attribute name and attribute value be the empty string.
Process the byte at position as follows:
Advance position to the next byte and return to the previous step.
Spaces: If the byte at position is one of 0x09 (HT), 0x0A (LF), 0x0C (FF), 0x0D (CR), or 0x20 (SP) then advance position to the next byte, then, repeat this step.
If the byte at position is not 0x3D (=), abort the get an attribute algorithm. The attribute's name is the value of attribute name, its value is the empty string.
Advance position past the 0x3D (=) byte.
Value: If the byte at position is one of 0x09 (HT), 0x0A (LF), 0x0C (FF), 0x0D (CR), or 0x20 (SP) then advance position to the next byte, then, repeat this step.
Process the byte at position as follows:
Process the byte at position as follows:
Advance position to the next byte and return to the previous step.
When the prescan a byte stream to determine its encoding algorithm is aborted without returning an encoding, get an XML encoding means doing this.
Looking for syntax resembling an XML declaration, even in text/html,
is necessary for compatibility with existing content.
Let encodingPosition be a pointer to the start of the stream.
If encodingPosition does not point to the start of a byte sequence 0x3C, 0x3F,
0x78, 0x6D, 0x6C (`<?xml`), then return failure.
Let xmlDeclarationEnd be a pointer to the next byte in the input byte stream which is 0x3E (>). If there is no such byte, then return failure.
Set encodingPosition to the position of the first occurrence of the
subsequence
of bytes 0x65, 0x6E, 0x63, 0x6F, 0x64, 0x69, 0x6E, 0x67 (`encoding`) at or
after the current encodingPosition. If there is no such sequence, then return
failure.
Advance encodingPosition past the 0x67 (g) byte.
While the byte at encodingPosition is less than or equal to 0x20 (i.e., it is either an ASCII space or control character), advance encodingPosition to the next byte.
If the byte at encodingPosition is not 0x3D (=), then return failure.
Advance encodingPosition to the next byte.
While the byte at encodingPosition is less than or equal to 0x20 (i.e., it is either an ASCII space or control character), advance encodingPosition to the next byte.
Let quoteMark be the byte at encodingPosition.
If quoteMark is not either 0x22 (") or 0x27 ('), then return failure.
Advance encodingPosition to the next byte.
Let encodingEndPosition be the position of the next occurrence of quoteMark at or after encodingPosition. If quoteMark does not occur again, then return failure.
Let potentialEncoding be the sequence of the bytes between encodingPosition (inclusive) and encodingEndPosition (exclusive).
If potentialEncoding contains one or more bytes whose byte value is 0x20 or below, then return failure.
Let encoding be the result of getting an encoding given potentialEncoding isomorphic decoded.
If the encoding is UTF-16BE/LE, then change it to UTF-8.
Return encoding.
For the sake of interoperability, user agents should not use a pre-scan algorithm that returns different results than the one described above. (But, if you do, please at least let us know, so that we can improve this algorithm and benefit everyone...)
User agents must support the encodings defined in Encoding, including, but not limited to, UTF-8, ISO-8859-2, ISO-8859-7, ISO-8859-8, windows-874, windows-1250, windows-1251, windows-1252, windows-1254, windows-1255, windows-1256, windows-1257, windows-1258, GBK, Big5, ISO-2022-JP, Shift_JIS, EUC-KR, UTF-16BE, UTF-16LE, UTF-16BE/LE, and x-user-defined. User agents must not support other encodings.
The above prohibits supporting, for example, CESU-8, UTF-7, BOCU-1, SCSU, EBCDIC, and UTF-32. This specification does not make any attempt to support prohibited encodings in its algorithms; support and use of prohibited encodings would thus lead to unexpected behavior. [CESU8] [UTF7] [BOCU1] [SCSU]
When the parser requires the user agent to change the encoding, it must run the following steps. This might happen if the encoding sniffing algorithm described above failed to find a character encoding, or if it found a character encoding that was not the actual encoding of the file.
If the encoding that is already being used to interpret the input stream is UTF-16BE/LE, then set the confidence to certain and return. The new encoding is ignored; if it was anything but the same encoding, then it would be clearly incorrect.
If the new encoding is UTF-16BE/LE, then change it to UTF-8.
If the new encoding is x-user-defined, then change it to windows-1252.
If the new encoding is identical or equivalent to the encoding that is already being used to interpret the input stream, then set the confidence to certain and return. This happens when the encoding information found in the file matches what the encoding sniffing algorithm determined to be the encoding, and in the second pass through the parser if the first pass found that the encoding sniffing algorithm described in the earlier section failed to find the right encoding.
If all the bytes up to the last byte converted by the current decoder have the same Unicode interpretations in both the current encoding and the new encoding, and if the user agent supports changing the converter on the fly, then the user agent may change to the new converter for the encoding on the fly. Set the document's character encoding and the encoding used to convert the input stream to the new encoding, set the confidence to certain, and return.
Otherwise, restart the navigate
algorithm, with historyHandling set to "replace"
and other inputs kept the same, but
this time skip the encoding
sniffing
algorithm
and instead just set the encoding to
the new encoding and the confidence
to
certain. Whenever possible, this should be done without actually contacting the
network
layer (the bytes should be re-parsed from memory), even if, e.g., the document is marked
as not
being cacheable. If this is not possible and contacting the network layer would involve
repeating
a request that uses a method other than `GET`, then instead set the confidence
to
certain and ignore the new
encoding. The resource will be misinterpreted. User agents may notify the user of the
situation,
to aid in application development.
This algorithm is only invoked when a new encoding is found declared on a
meta
element.
The input stream consists of the characters pushed into it as the input byte stream is decoded or from the various APIs that directly manipulate the input stream.
Any occurrences of surrogates are surrogate-in-input-stream parse errors. Any occurrences of noncharacters are noncharacter-in-input-stream parse errors and any occurrences of controls other than ASCII whitespace and U+0000 NULL characters are control-character-in-input-stream parse errors.
The handling of U+0000 NULL characters varies based on where the characters are found and happens at the later stages of the parsing. They are either ignored or, for security reasons, replaced with a U+FFFD REPLACEMENT CHARACTER. This handling is, by necessity, spread across both the tokenization stage and the tree construction stage.
Before the tokenization stage, the input stream must be preprocessed by normalizing newlines. Thus, newlines in HTML DOMs are represented by U+000A LF characters, and there are never any U+000D CR characters in the input to the tokenization stage.
The next input character is the first character in the input stream that has not yet been consumed or explicitly ignored by the requirements in this section. Initially, the next input character is the first character in the input. The current input character is the last character to have been consumed.
The insertion point is the position (just before a character or
just before
the end
of the input stream) where content inserted using document.write()
is actually inserted. The insertion point is
relative to the position of the character immediately after it, it is not an absolute offset
into
the input stream. Initially, the insertion point is undefined.
The "EOF" character in the tables below is a conceptual character representing the end of the
input stream. If the
parser
is a script-created
parser, then the end of
the input stream is
reached
when an
explicit "EOF" character (inserted by
the document.close()
method) is consumed. Otherwise, the
"EOF" character is not a real character in the stream, but rather the lack of any further
characters.
The insertion mode is a state variable that controls the primary operation of the tree construction stage.
Initially, the insertion mode is "initial". It can change to "before html", "before head", "in head", "in head noscript", "after head", "in body", "text", "in table", "in table text", "in caption", "in column group", "in table body", "in row", "in cell", "in select", "in select in table", "in template", "after body", "in frameset", "after frameset", "after after body", and "after after frameset" during the course of the parsing, as described in the tree construction stage. The insertion mode affects how tokens are processed and whether CDATA sections are supported.
Several of these modes, namely "in head", "in body", "in table", and "in select", are special, in that the other modes defer to them at various times. When the algorithm below says that the user agent is to do something "using the rules for the m insertion mode", where m is one of these modes, the user agent must use the rules described under the m insertion mode's section, but must leave the insertion mode unchanged unless the rules in m themselves switch the insertion mode to a new value.
When the insertion mode is switched to "text" or "in table text", the original insertion mode is also set. This is the insertion mode to which the tree construction stage will return.
Similarly, to parse nested template
elements, a
stack of template insertion
modes is used. It is initially empty. The current
template
insertion mode is the
insertion mode that was most recently added to the stack of template insertion
modes.
The algorithms in the sections below will push insertion modes onto this stack, meaning
that the specified insertion mode is to be added to the stack, and pop insertion modes
from
the stack, which means that the most recently added insertion mode must be removed from the
stack.
When the steps below require the UA to reset the insertion mode appropriately, it means the UA must follow these steps:
Let last be false.
Let node be the last node in the stack of open elements.
Loop: If node is the first node in the stack of open elements, then set last to true, and, if the parser was created as part of the HTML fragment parsing algorithm (fragment case), set node to the context element passed to that algorithm.
If node is a select
element, run
these substeps:
If last is true, jump to the step below labeled done.
Let ancestor be node.
Loop: If ancestor is the first node in the stack of open elements, jump to the step below labeled done.
Let ancestor be the node before ancestor in the stack of open elements.
If ancestor is a template
node, jump to the step below
labeled done.
If ancestor is a table
node,
switch the insertion
mode to "in select in table"
and return.
Jump back to the step labeled loop.
Done: Switch the insertion mode to "in select" and return.
If node is a td
or th
element and
last is
false, then switch the insertion
mode
to "in
cell" and return.
If node is a tr
element, then switch the insertion
mode to "in
row" and
return.
If node is a tbody,
thead,
or
tfoot
element, then
switch the insertion
mode to
"in table
body"
and
return.
If node is a caption
element,
then switch the
insertion mode to
"in
caption"
and
return.
If node is a colgroup
element, then switch the
insertion mode to
"in
column
group" and return.
If node is a table
element, then
switch the
insertion mode to
"in
table" and
return.
If node is a template
element, then switch the
insertion mode to
the current
template insertion mode and
return.
If node is a head
element and
last is
false, then switch the insertion
mode to "in
head" and return.
If node is a body
element,
then
switch the
insertion mode to
"in body"
and
return.
If node is a frameset
element, then switch the
insertion mode to
"in
frameset" and
return. (fragment case)
If node is an html
element,
run these
substeps:
If the head
element pointer is null, switch the
insertion
mode to
"before head"
and return. (fragment
case)
Otherwise, the head element
pointer
is not
null, switch the
insertion
mode to
"after head" and
return.
If last is true, then switch the insertion mode to "in body" and return. (fragment case)
Let node now be the node before node in the stack of open elements.
Return to the step labeled loop.
Initially, the stack of open elements is empty. The stack grows downwards; the topmost node on the stack is the first one added to the stack, and the bottommost node of the stack is the most recently added node in the stack (notwithstanding when the stack is manipulated in a random access fashion as part of the handling for misnested tags).
The "before html"
insertion mode creates
the
html
document
element, which is
then added to the stack.
In the fragment
case,
the stack
of open
elements
is
initialized to contain an html
element
that is
created as part of that algorithm. (The fragment case skips
the
"before
html" insertion
mode.)
The html
node,
however it is created, is the topmost node of the stack. It only
gets popped off the stack when the parser finishes.
The current node is the bottommost node in this stack of open elements.
The adjusted current node is the context element if the parser was created as part of the HTML fragment parsing algorithm and the stack of open elements has only one element in it (fragment case); otherwise, the adjusted current node is the current node.
When the current node is removed from the stack of open elements, process internal resource links given the current node's node document.
Elements in the stack of open elements fall into the following categories:
The following elements have varying levels of special parsing rules: HTML's
address,
applet, area,
article,
aside,
base,
basefont,
bgsound,
blockquote,
body,
br,
button,
caption,
center, col,
colgroup,
dd,
details,
dir, div,
dl,
dt,
embed,
fieldset,
figcaption,
figure,
footer,
form,
frame,
frameset,
h1,
h2,
h3,
h4,
h5,
h6,
head,
header,
hgroup,
hr,
html,
iframe,
img,
input,
keygen, li,
link,
listing, main,
marquee,
menu,
meta,
nav,
noembed, noframes,
noscript,
object,
ol,
p,
param, plaintext,
pre,
script,
search,
section,
select,
source,
style,
summary,
table,
tbody,
td,
template,
textarea,
tfoot,
th,
thead,
title,
tr,
track,
ul,
wbr,
xmp; MathML
mi,
MathML mo, MathML
mn, MathML
ms, MathML
mtext, and MathML
annotation-xml; and SVG foreignObject, SVG
desc, and SVG
title.
An image start tag token is handled by the tree builder,
but it is not in this list because it is not an element; it gets turned into an img
element.
The following HTML elements are those that end up in the list of active
formatting
elements: a,
b,
big, code,
em,
font, i,
nobr, s,
small,
strike, strong,
tt, and
u.
All other elements found while parsing an HTML document.
Typically, the special
elements
have the
start and end tag tokens
handled specifically, while ordinary
elements'
tokens fall into "any other start tag"
and "any other end tag" clauses, and some parts of the tree builder check if a particular
element
in the stack of
open
elements is in the special
category.
However, some
elements (e.g., the option
element) have
their start or end tag tokens handled
specifically, but are still not in the special
category, so that they get the
ordinary handling elsewhere.
The stack of open elements is said to have an element target node in a specific scope consisting of a list of element types list when the following algorithm terminates in a match state:
Initialize node to be the current node (the bottommost node of the stack).
If node is the target node, terminate in a match state.
Otherwise, if node is one of the element types in list, terminate in a failure state.
Otherwise, set node to the previous entry in the stack of open
elements and return to step 2. (This will never fail, since the loop will always
terminate
in the previous step if the top of the stack — an html
element —
is
reached.)
The stack of open elements is said to have a particular element in scope when it has that element in the specific scope consisting of the following element types:
applet
caption
html
table
td
th
marquee
object
template
mi
mo
mn
ms
mtext
annotation-xml
foreignObject
desc
title
The stack of open elements is said to have a particular element in list item scope when it has that element in the specific scope consisting of the following element types:
ol
in the HTML
namespace
ul
in the HTML
namespace
The stack of open elements is said to have a particular element in button scope when it has that element in the specific scope consisting of the following element types:
button
in
the HTML
namespace
The stack of open elements is said to have a particular element in table scope when it has that element in the specific scope consisting of the following element types:
html
in
the HTML
namespace
table
in the
HTML
namespace
template
in the HTML
namespace
The stack of open elements is said to have a particular element in select scope when it has that element in the specific scope consisting of all element types except the following:
optgroup
in the HTML
namespace
option
in
the HTML
namespace
Nothing happens if at any time any of the elements in the stack of open elements
are moved to a new location in, or removed from, the Document tree. In
particular,
the stack is not changed in this situation. This can cause, amongst other strange effects,
content
to be appended to nodes that are no longer in the DOM.
In some cases (namely, when closing misnested formatting elements), the stack is manipulated in a random-access fashion.
Initially, the list of active formatting elements is empty. It is used to handle mis-nested formatting element tags.
The list contains elements in the formatting category, and markers.
The
markers are inserted when entering applet,
object,
marquee,
template,
td,
th,
and caption
elements, and are used to prevent formatting from
"leaking" into applet, object,
marquee,
template,
td,
th,
and caption
elements.
In addition, each element in the list of active formatting elements is associated with the token for which it was created, so that further elements can be created for that token if necessary.
When the steps below require the UA to push onto the list of active formatting elements an element element, the UA must perform the following steps:
If there are already three elements in the list of active formatting elements after the last marker, if any, or anywhere in the list if there are no markers, that have the same tag name, namespace, and attributes as element, then remove the earliest such element from the list of active formatting elements. For these purposes, the attributes must be compared as they were when the elements were created by the parser; two elements have the same attributes if all their parsed attributes can be paired such that the two attributes in each pair have identical names, namespaces, and values (the order of the attributes does not matter).
This is the Noah's Ark clause. But with three per family instead of two.
Add element to the list of active formatting elements.
When the steps below require the UA to reconstruct the active formatting elements, the UA must perform the following steps:
If there are no entries in the list of active formatting elements, then there is nothing to reconstruct; stop this algorithm.
If the last (most recently added) entry in the list of active formatting elements is a marker, or if it is an element that is in the stack of open elements, then there is nothing to reconstruct; stop this algorithm.
Let entry be the last (most recently added) element in the list of active formatting elements.
Rewind: If there are no entries before entry in the list of active formatting elements, then jump to the step labeled create.
Let entry be the entry one earlier than entry in the list of active formatting elements.
If entry is neither a marker nor an element that is also in the stack of open elements, go to the step labeled rewind.
Advance: Let entry be the element one later than entry in the list of active formatting elements.
Create: Insert an HTML element for the token for which the element entry was created, to obtain new element.
Replace the entry for entry in the list with an entry for new element.
If the entry for new element in the list of active formatting elements is not the last entry in the list, return to the step labeled advance.
This has the effect of reopening all the formatting elements that were opened in the current body, cell, or caption (whichever is youngest) that haven't been explicitly closed.
The way this specification is written, the list of active formatting elements always consists of elements in chronological order with the least recently added element first and the most recently added element last (except for while steps 7 to 10 of the above algorithm are being executed, of course).
When the steps below require the UA to clear the list of active formatting elements up to the last marker, the UA must perform the following steps:
Let entry be the last (most recently added) entry in the list of active formatting elements.
Remove entry from the list of active formatting elements.
If entry was a marker, then stop the algorithm at this point. The list has been cleared up to the last marker.
Go to step 1.
Initially, the head element pointer and the form element pointer are both null.
Once a head
element
has been
parsed (whether implicitly or explicitly) the
head
element
pointer
gets set to point to this node.
The form
element
pointer points to the last
form element
that
was opened
and whose end tag has not yet been seen. It is used to
make form controls associate with forms in the face of dramatically bad markup, for historical
reasons. It is ignored inside template
elements.
The scripting flag is set to "enabled" if scripting
was enabled for the Document
with which the parser is associated when the
parser was created, and "disabled" otherwise.
The scripting
flag can
be
enabled even when the parser was created as
part of the HTML fragment parsing
algorithm,
even
though script
elements
don't execute in that case.
The frameset-ok flag is set to "ok" when the parser is created. It is set to "not ok" after certain tokens are seen.
Implementations must act as if they used the following state machine to tokenize HTML. The state machine must start in the data state. Most states consume a single character, which may have various side-effects, and either switches the state machine to a new state to reconsume the current input character, or switches it to a new state to consume the next character, or stays in the same state to consume the next character. Some states have more complicated behavior and can consume several characters before switching to another state. In some cases, the tokenizer state is also changed by the tree construction stage.
When a state says to reconsume a matched character in a specified state, that means to switch to that state, but when it attempts to consume the next input character, provide it with the current input character instead.
The exact behavior of certain states depends on the insertion mode and the stack of open elements. Certain states also use a temporary buffer to track progress, and the character reference state uses a return state to return to the state it was invoked from.
The output of the tokenization step is a series of zero or more of the following tokens: DOCTYPE, start tag, end tag, comment, character, end-of-file. DOCTYPE tokens have a name, a public identifier, a system identifier, and a force-quirks flag. When a DOCTYPE token is created, its name, public identifier, and system identifier must be marked as missing (which is a distinct state from the empty string), and the force-quirks flag must be set to off (its other state is on). Start and end tag tokens have a tag name, a self-closing flag, and a list of attributes, each of which has a name and a value. When a start or end tag token is created, its self-closing flag must be unset (its other state is that it be set), and its attributes list must be empty. Comment and character tokens have data.
When a token is emitted, it must immediately be handled by the tree construction
stage. The tree construction stage can affect the state of the tokenization stage, and can
insert
additional characters into the stream. (For example, the script element can
result
in
scripts executing and using the dynamic markup insertion APIs to insert
characters
into the stream being tokenized.)
Creating a token and emitting it are distinct actions. It is possible for a token to be created but implicitly abandoned (never emitted), e.g. if the file ends unexpectedly while processing the characters that are being parsed into a start tag token.
When a start tag token is emitted with its self-closing flag set, if the flag is not acknowledged when it is processed by the tree construction stage, that is a non-void-html-element-start-tag-with-trailing-solidus parse error.
When an end tag token is emitted with attributes, that is an end-tag-with-attributes parse error.
When an end tag token is emitted with its self-closing flag set, that is an end-tag-with-trailing-solidus parse error.
An appropriate end tag token is an end tag token whose tag name matches the tag name of the last start tag to have been emitted from this tokenizer, if any. If no start tag has been emitted from this tokenizer, then no end tag token is appropriate.
A character reference is said to be consumed as part of an attribute if the return state is either attribute value (double-quoted) state, attribute value (single-quoted) state or attribute value (unquoted) state.
When a state says to flush code points consumed as a character reference, it means that for each code point in the temporary buffer (in the order they were added to the buffer) user agent must append the code point from the buffer to the current attribute's value if the character reference was consumed as part of an attribute, or emit the code point as a character token otherwise.
Before each step of the tokenizer, the user agent must first check the parser pause flag. If it is true, then the tokenizer must abort the processing of any nested invocations of the tokenizer, yielding control back to the caller.
The tokenizer state machine consists of the states defined in the following subsections.
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
script", then switch to the script data
double
escaped
state.
Otherwise, switch to the script data escaped
state. Emit
the current input
character as a character token.
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
script", then switch to the script
data escaped state. Otherwise,
switch to the script data
double
escaped
state. Emit the current input
character as a character token.
Consume the next input character:
Consume the next input character:
When the user agent leaves the attribute name state (and before emitting the tag token, if appropriate), the complete attribute's name must be compared to the other attributes on the same token; if there is already an attribute on the token with the exact same name, then this is a duplicate-attribute parse error and the new attribute must be removed from the token.
If an attribute is so removed from a token, it, and the value that gets associated with it, if any, are never subsequently used by the parser, and are therefore effectively discarded. Removing the attribute in this way does not change its status as the "current attribute" for the purposes of the tokenizer, however.
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
If the next few characters are:
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
If the six characters starting from the current input character are an ASCII case-insensitive match for the word "PUBLIC", then consume those characters and switch to the after DOCTYPE public keyword state.
Otherwise, if the six characters starting from the current input character are an ASCII case-insensitive match for the word "SYSTEM", then consume those characters and switch to the after DOCTYPE system keyword state.
Otherwise, this is an invalid-character-sequence-after-doctype-name parse error. Set the current DOCTYPE token's force-quirks flag to on. Reconsume in the bogus DOCTYPE state.
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
U+0000 NULL characters are handled in the tree construction stage, as part of the in foreign content insertion mode, which is the only place where CDATA sections can appear.
Consume the next input character:
Consume the next input character:
Set the temporary buffer to the empty string. Append a U+0026 AMPERSAND (&) character to the temporary buffer. Consume the next input character:
Consume the maximum number of characters possible, where the consumed characters are one of the identifiers in the first column of the named character references table. Append each character to the temporary buffer when it's consumed.
If the character reference was consumed as part of an attribute, and the last character matched is not a U+003B SEMICOLON character (;), and the next input character is either a U+003D EQUALS SIGN character (=) or an ASCII alphanumeric, then, for historical reasons, flush code points consumed as a character reference and switch to the return state.
Otherwise:
If the last character matched is not a U+003B SEMICOLON character (;), then this is a missing-semicolon-after-character-reference parse error.
Set the temporary buffer to the empty string. Append one or two characters corresponding to the character reference name (as given by the second column of the named character references table) to the temporary buffer.
If the markup contains (not in an attribute) the string I'm ¬it; I
tell you, the character reference is parsed as "not", as in, I'm ¬it;
I tell you (and this is a parse error). But if the markup was I'm
∉ I tell you, the character reference would be parsed as "notin;", resulting
in I'm ∉ I tell you (and no parse error).
However, if the markup contains the string I'm ¬it; I tell you
in an attribute, no character reference is parsed and string remains intact (and there is no
parse error).
Consume the next input character:
Set the character reference code to zero (0).
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
Check the character reference code:
If the number is 0x00, then this is a null-character-reference parse error. Set the character reference code to 0xFFFD.
If the number is greater than 0x10FFFF, then this is a character-reference-outside-unicode-range parse error. Set the character reference code to 0xFFFD.
If the number is a surrogate, then this is a surrogate-character-reference parse error. Set the character reference code to 0xFFFD.
If the number is a noncharacter, then this is a noncharacter-character-reference parse error.
If the number is 0x0D, or a control that's not ASCII whitespace, then this is a control-character-reference parse error. If the number is one of the numbers in the first column of the following table, then find the row with that number in the first column, and set the character reference code to the number in the second column of that row.
| Number | Code point | |
|---|---|---|
| 0x80 | 0x20AC | EURO SIGN (€) |
| 0x82 | 0x201A | SINGLE LOW-9 QUOTATION MARK (‚) |
| 0x83 | 0x0192 | LATIN SMALL LETTER F WITH HOOK (ƒ) |
| 0x84 | 0x201E | DOUBLE LOW-9 QUOTATION MARK („) |
| 0x85 | 0x2026 | HORIZONTAL ELLIPSIS (…) |
| 0x86 | 0x2020 | DAGGER (†) |
| 0x87 | 0x2021 | DOUBLE DAGGER (‡) |
| 0x88 | 0x02C6 | MODIFIER LETTER CIRCUMFLEX ACCENT (ˆ) |
| 0x89 | 0x2030 | PER MILLE SIGN (‰) |
| 0x8A | 0x0160 | LATIN CAPITAL LETTER S WITH CARON (Š) |
| 0x8B | 0x2039 | SINGLE LEFT-POINTING ANGLE QUOTATION MARK (‹) |
| 0x8C | 0x0152 | LATIN CAPITAL LIGATURE OE (Œ) |
| 0x8E | 0x017D | LATIN CAPITAL LETTER Z WITH CARON (Ž) |
| 0x91 | 0x2018 | LEFT SINGLE QUOTATION MARK (‘) |
| 0x92 | 0x2019 | RIGHT SINGLE QUOTATION MARK (’) |
| 0x93 | 0x201C | LEFT DOUBLE QUOTATION MARK (“) |
| 0x94 | 0x201D | RIGHT DOUBLE QUOTATION MARK (”) |
| 0x95 | 0x2022 | BULLET (•) |
| 0x96 | 0x2013 | EN DASH (–) |
| 0x97 | 0x2014 | EM DASH (—) |
| 0x98 | 0x02DC | SMALL TILDE (˜) |
| 0x99 | 0x2122 | TRADE MARK SIGN (™) |
| 0x9A | 0x0161 | LATIN SMALL LETTER S WITH CARON (š) |
| 0x9B | 0x203A | SINGLE RIGHT-POINTING ANGLE QUOTATION MARK (›) |
| 0x9C | 0x0153 | LATIN SMALL LIGATURE OE (œ) |
| 0x9E | 0x017E | LATIN SMALL LETTER Z WITH CARON (ž) |
| 0x9F | 0x0178 | LATIN CAPITAL LETTER Y WITH DIAERESIS (Ÿ) |
Set the temporary buffer to the empty string. Append a code point equal to the character reference code to the temporary buffer. Flush code points consumed as a character reference. Switch to the return state.
The input to the tree construction stage is a sequence of tokens from the
tokenization stage. The tree
construction
stage is
associated with a DOM
Document object when a parser
is
created. The
"output" of this stage consists of
dynamically modifying or extending that document's DOM tree.
This specification does not define when an interactive user agent has to render the
Document so that it is
available to
the user,
or when it has to begin accepting user
input.
As each token is emitted from the tokenizer, the user agent must follow the appropriate steps from the following list, known as the tree construction dispatcher:
annotation-xml element and the token is a start tag whose tag name is
"svg"
The next token is the token that is about to be processed by the tree construction dispatcher (even if the token is subsequently just ignored).
A node is a MathML text integration point if it is one of the following elements:
mi element
mo element
mn element
ms element
mtext element
A node is an HTML integration point if it is one of the following elements:
annotation-xml element
whose start
tag
token had an
attribute with the name "encoding" whose value was an ASCII
case-insensitive match
for the string "text/html"
annotation-xml element
whose start
tag
token had an
attribute with the name "encoding" whose value was an ASCII
case-insensitive match
for the string "application/xhtml+xml"
foreignObject element
desc element
title element
If the node in question is the context element passed to the HTML fragment parsing algorithm, then the start tag token for that element is the "fake" token created during by that HTML fragment parsing algorithm.
Not all of the tag names mentioned below are conformant tag names in this specification; many are included to handle legacy content. They still form part of the algorithm that implementations are required to implement to claim conformance.
The algorithm described below places no limit on the depth of the DOM tree
generated, or on the length of tag names, attribute names, attribute values, Text
nodes, etc. While implementers are encouraged to avoid
arbitrary limits, it is
recognized that practical concerns will likely force user agents to impose nesting depth
constraints.
While the parser is processing a token, it can enable or disable foster parenting. This affects the following algorithm.
The appropriate place for inserting a node, optionally using a particular override target, is the position in an element returned by running the following steps:
If there was an override target specified, then let target be the override target.
Otherwise, let target be the current node.
Determine the adjusted insertion location using the first matching steps from the following list:
table,
tbody,
tfoot,
thead,
or tr
element
Foster parenting happens when content is misnested in tables.
Run these substeps:
Let last template be the last template
element in the
stack of open
elements,
if any.
Let last table be the last table
element in the
stack of
open
elements,
if any.
If there is a last template and either there is no last table, or there is one, but last template is lower (more recently added) than last table in the stack of open elements, then: let adjusted insertion location be inside last template's template contents, after its last child (if any), and abort these steps.
If there is no last table, then let adjusted insertion
location be inside the first element in the stack of
open
elements
(the
html
element), after its last child (if any), and abort these steps.
(fragment
case)
If last table has a parent node, then let adjusted insertion location be inside last table's parent node, immediately before last table, and abort these steps.
Let previous element be the element immediately above last table in the stack of open elements.
Let adjusted insertion location be inside previous element, after its last child (if any).
These steps are involved in part because it's possible for elements,
the
table
element in this case in particular, to have been moved by a script around
in the DOM, or indeed removed from the DOM entirely, after the element was
inserted by
the
parser.
Let adjusted insertion location be inside target, after its last child (if any).
If the adjusted insertion location is inside a template
element, let it instead be inside the template
element's template
contents, after its last child (if any).
Return the adjusted insertion location.
When the steps below require the UA to create an element for a token in a particular given namespace and with a particular intended parent, the UA must run the following steps:
If the active speculative HTML parser is not null, then return the result of creating a speculative mock element given given namespace, the tag name of the given token, and the attributes of the given token.
Otherwise, optionally create a speculative mock element given given namespace, the tag name of the given token, and the attributes of the given token.
The result is not used. This step allows for a speculative fetch to be initiated from non-speculative parsing. The fetch is still speculative at this point, because, for example, by the time the element is inserted, intended parent might have been removed from the document.
Let document be intended parent's node document.
Let local name be the tag name of the token.
Let is be the value of the "is" attribute in
the
given token, if such an attribute exists, or null otherwise.
Let definition be the result of looking up a custom element definition given document, given namespace, local name, and is.
If definition is non-null and the parser was not created as part of the HTML fragment parsing algorithm, then let will execute script be true. Otherwise, let it be false.
If will execute script is true, then:
Increment document's throw-on-dynamic-markup-insertion counter.
If the JavaScript execution context stack is empty, then perform a microtask checkpoint.
Push a new element queue onto document's relevant agent's custom element reactions stack.
Let element be the result of creating an element given document, localName, given namespace, null, and is. If will execute script is true, set the synchronous custom elements flag; otherwise, leave it unset.
This will cause custom element constructors to run, if will execute script is true. However, since we incremented the throw-on-dynamic-markup-insertion counter, this cannot cause new characters to be inserted into the tokenizer, or the document to be blown away.
Append each attribute in the given token to element.
This can enqueue a
custom
element
callback reaction for the
attributeChangedCallback, which might run immediately (in the next
step).
Even though the is
attribute governs the creation
of a customized built-in
element,
it is
not present during the execution of the relevant custom element
constructor;
it is
appended in this step, along with all other attributes.
If will execute script is true, then:
Let queue be the result of popping from document's relevant agent's custom element reactions stack. (This will be the same element queue as was pushed above.)
Invoke custom element reactions in queue.
Decrement document's throw-on-dynamic-markup-insertion counter.
If element has an xmlns attribute in the XMLNS
namespace whose value is not exactly the same as the element's
namespace, that
is a
parse error.
Similarly,
if
element has an xmlns:xlink attribute in the XMLNS
namespace whose value is not the
XLink
Namespace, that is a parse
error.
If element is a resettable element, invoke its reset algorithm. (This initializes the element's value and checkedness based on the element's attributes.)
If element is a form-associated element
and not
a
form-associated
custom
element,
the
form
element pointer is not null, there is no
template
element on the stack of open elements,
element is
either not listed
or
doesn't have a form
attribute, and
the intended parent is in the same
tree as the element pointed to by the form element
pointer, then associate
element
with the form
element
pointed to by the form element
pointer and set element's parser inserted flag.
Return element.
To insert an element at the adjusted insertion location with an element element:
Let the adjusted insertion location be the appropriate place for inserting a node.
If it is not possible to insert element at the adjusted insertion location, abort these steps.
If the parser was not created as part of the HTML fragment parsing algorithm, then push a new element queue onto element's relevant agent's custom element reactions stack.
Insert element at the adjusted insertion location.
If the parser was not created as part of the HTML fragment parsing algorithm, then pop the element queue from element's relevant agent's custom element reactions stack, and invoke custom element reactions in that queue.
If the adjusted insertion location cannot accept more elements, e.g.,
because it's a Document that
already
has an element child, then element is
dropped on the floor.
When the steps below require the user agent to insert a foreign element for a token in a given namespace and with a boolean onlyAddToElementStack, the user agent must run these steps:
Let the adjusted insertion location be the appropriate place for inserting a node.
Let element be the result of creating an element for the token in the given namespace, with the intended parent being the element in which the adjusted insertion location finds itself.
If onlyAddToElementStack is false, then run insert an element at the adjusted insertion location with element.
Push element onto the stack of open elements so that it is the new current node.
Return element.
When the steps below require the user agent to insert an HTML element for a token, the user agent must insert a foreign element for the token, with the HTML namespace and false.
When the steps below require the user agent to adjust MathML
attributes
for a token,
then, if the token has an attribute named definitionurl, change its name to
definitionURL (note the case difference).
When the steps below require the user agent to adjust SVG attributes for a token, then, for each attribute on the token whose attribute name is one of the ones in the first column of the following table, change the attribute's name to the name given in the corresponding cell in the second column. (This fixes the case of SVG attributes that are not all lowercase.)
| Attribute name on token | Attribute name on element |
|---|---|
attributename
| attributeName
|
attributetype
| attributeType
|
basefrequency
| baseFrequency
|
baseprofile
| baseProfile
|
calcmode
| calcMode
|
clippathunits
| clipPathUnits
|
diffuseconstant
| diffuseConstant
|
edgemode
| edgeMode
|
filterunits
| filterUnits
|
glyphref
| glyphRef
|
gradienttransform
| gradientTransform
|
gradientunits
| gradientUnits
|
kernelmatrix
| kernelMatrix
|
kernelunitlength
| kernelUnitLength
|
keypoints
| keyPoints
|
keysplines
| keySplines
|
keytimes
| keyTimes
|
lengthadjust
| lengthAdjust
|
limitingconeangle
| limitingConeAngle
|
markerheight
| markerHeight
|
markerunits
| markerUnits
|
markerwidth
| markerWidth
|
maskcontentunits
| maskContentUnits
|
maskunits
| maskUnits
|
numoctaves
| numOctaves
|
pathlength
| pathLength
|
patterncontentunits
| patternContentUnits
|
patterntransform
| patternTransform
|
patternunits
| patternUnits
|
pointsatx
| pointsAtX
|
pointsaty
| pointsAtY
|
pointsatz
| pointsAtZ
|
preservealpha
| preserveAlpha
|
preserveaspectratio
| preserveAspectRatio
|
primitiveunits
| primitiveUnits
|
refx
| refX
|
refy
| refY
|
repeatcount
| repeatCount
|
repeatdur
| repeatDur
|
requiredextensions
| requiredExtensions
|
requiredfeatures
| requiredFeatures
|
specularconstant
| specularConstant
|
specularexponent
| specularExponent
|
spreadmethod
| spreadMethod
|
startoffset
| startOffset
|
stddeviation
| stdDeviation
|
stitchtiles
| stitchTiles
|
surfacescale
| surfaceScale
|
systemlanguage
| systemLanguage
|
tablevalues
| tableValues
|
targetx
| targetX
|
targety
| targetY
|
textlength
| textLength
|
viewbox
| viewBox
|
viewtarget
| viewTarget
|
xchannelselector
| xChannelSelector
|
ychannelselector
| yChannelSelector
|
zoomandpan
| zoomAndPan
|
When the steps below require the user agent to adjust foreign
attributes
for a
token, then, if any of the attributes on the token match the strings given in the first column
of
the following table, let the attribute be a namespaced attribute, with the prefix being the
string
given in the corresponding cell in the second column, the local name being the string given in
the
corresponding cell in the third column, and the namespace being the namespace given in the
corresponding cell in the fourth column. (This fixes the use of namespaced attributes, in
particular lang attributes in the XML
namespace.)
| Attribute name | Prefix | Local name | Namespace |
|---|---|---|---|
xlink:actuate
| xlink
| actuate
| XLink namespace |
xlink:arcrole
| xlink
| arcrole
| XLink namespace |
xlink:href
| xlink
| href
| XLink namespace |
xlink:role
| xlink
| role
| XLink namespace |
xlink:show
| xlink
| show
| XLink namespace |
xlink:title
| xlink
| title
| XLink namespace |
xlink:type
| xlink
| type
| XLink namespace |
xml:lang
| xml
| lang
| XML namespace |
xml:space
| xml
| space
| XML namespace |
xmlns
| (none) | xmlns
| XMLNS namespace |
xmlns:xlink
| xmlns
| xlink
| XMLNS namespace |
When the steps below require the user agent to insert a character while processing a token, the user agent must run the following steps:
Let data be the characters passed to the algorithm, or, if no characters were explicitly specified, the character of the character token being processed.
Let the adjusted insertion location be the appropriate place for inserting a node.
If the adjusted insertion location is in a Document
node,
then return.
The DOM will not let Document
nodes have
Text
node
children, so they are dropped on the floor.
If there is a Text
node immediately before the adjusted insertion
location, then append data to that Text
node's data.
Otherwise, create a new Text
node whose data
is
data and
whose node
document is the same as that of the
element in which the adjusted insertion location finds itself, and insert
the newly created node at the adjusted insertion location.
Here are some sample inputs to the parser and the corresponding number of Text
nodes that they result in, assuming a user agent that executes scripts.
| Input | Number of Text
nodes
|
|---|---|
| One Text
node in the document, containing "AB".
|
| Three Text
nodes; "A" before the script, the script's contents, and "BC" after the script
(the
parser
appends to the Text
node created by the script).
|
| Two adjacent Text
nodes in the document, containing "A" and "BC".
|
| One Text
node before the table, containing "ABCD". (This is caused by foster
parenting.)
|
| One Text
node before the table, containing "A B C" (A-space-B-space-C). (This is caused
by foster
parenting.)
|
| One Text
node before the table, containing "A BC" (A-space-B-C), and one Text
node inside the table (as a child of a tbody)
with a single space character. (Space characters separated from non-space
characters by
non-character tokens are not affected by foster parenting, even
if those
other
tokens then get ignored.)
|
When the steps below require the user agent to insert a comment while processing a comment token, optionally with an explicitly insertion position position, the user agent must run the following steps:
Let data be the data given in the comment token being processed.
If position was specified, then let the adjusted insertion location be position. Otherwise, let adjusted insertion location be the appropriate place for inserting a node.
Create a Comment
node whose data attribute is set to
data and whose node
document is
the same as that of the node in which the adjusted insertion location finds
itself.
Insert the newly created node at the adjusted insertion location.
DOM mutation events must not fire for changes caused by the UA
parsing the document. This includes the parsing of any content inserted using document.write()
and document.writeln()
calls. [UIEVENTS]
However, mutation observers do fire, as required by DOM .
The generic raw text element parsing algorithm and the generic RCDATA element parsing algorithm consist of the following steps. These algorithms are always invoked in response to a start tag token.
Insert an HTML element for the token.
If the algorithm that was invoked is the generic raw text element parsing algorithm, switch the tokenizer to the RAWTEXT state; otherwise the algorithm invoked was the generic RCDATA element parsing algorithm, switch the tokenizer to the RCDATA state.
Let the original insertion mode be the current insertion mode.
Then, switch the insertion mode to "text".
When the steps below require the UA to generate implied end
tags,
then,
while the
current
node is a
dd
element,
a dt
element, an
li
element, an optgroup
element, an option
element, a
p
element,
an rb element, an
rp
element,
an rt
element, or an rtc
element, the
UA must pop the current
node off the
stack
of
open elements.
If a step requires the UA to generate implied end tags but lists an element to exclude from the process, then the UA must perform the above steps as if that element was not in the above list.
When the steps below require the UA to generate
all
implied end
tags thoroughly,
then, while the current
node is a caption
element, a
colgroup
element, a dd
element, a dt
element, an
li
element, an optgroup
element, an option
element, a
p
element, an rb
element,
an
rp
element, an rt
element, an rtc
element, a
tbody
element, a td
element,
a
tfoot
element, a th
element,
a thead
element, or a
tr
element, the UA must pop the current node off the
stack of
open elements.
A Document object has
an
associated
parser cannot change the mode flag
(a boolean). It is initially false.
When the user agent is to apply the rules for the "initial" insertion mode, the user agent must handle the token as follows:
Ignore the token.
Insert a
comment as
the last
child of the Document
object.
If the DOCTYPE token's name is not "html", or the token's public
identifier is not missing, or the token's system identifier is neither missing nor
"about:legacy-compat",
then there is a parse
error.
Append a DocumentType
node to the Document
node,
with its name
set
to the name given in the DOCTYPE token, or the
empty string if the name was missing; its public
ID set to the public identifier given in the DOCTYPE token, or the empty string
if the
public identifier was missing; and its system ID
set to the system identifier given in the DOCTYPE token, or the empty string if the
system
identifier was missing.
This also ensures that the DocumentType
node is returned as the
value of the doctype
attribute of the
Document
object.
Then, if the document is not an iframe
srcdoc document, and the parser cannot
change the mode flag is false, and the DOCTYPE token matches one of the
conditions in
the
following list, then set the Document to quirks
mode:
html".
-//W3O//DTD W3 HTML Strict 3.0//EN//"
-/W3C/DTD HTML 4.0 Transitional/EN"
HTML"
http://www.ibm.com/data/dtd/v11/ibmxhtml1-transitional.dtd"
+//Silmaril//dtd html Pro v0r11 19970101//"
-//AS//DTD HTML 3.0 asWedit + extensions//"
-//AdvaSoft Ltd//DTD HTML 3.0 asWedit + extensions//"
-//IETF//DTD HTML 2.0 Level 1//"
-//IETF//DTD HTML 2.0 Level 2//"
-//IETF//DTD HTML 2.0 Strict Level 1//"
-//IETF//DTD HTML 2.0 Strict Level 2//"
-//IETF//DTD HTML 2.0 Strict//"
-//IETF//DTD HTML 2.0//"
-//IETF//DTD HTML 2.1E//"
-//IETF//DTD HTML 3.0//"
-//IETF//DTD HTML 3.2 Final//"
-//IETF//DTD HTML 3.2//"
-//IETF//DTD HTML 3//"
-//IETF//DTD HTML Level 0//"
-//IETF//DTD HTML Level 1//"
-//IETF//DTD HTML Level 2//"
-//IETF//DTD HTML Level 3//"
-//IETF//DTD HTML Strict Level 0//"
-//IETF//DTD HTML Strict Level 1//"
-//IETF//DTD HTML Strict Level 2//"
-//IETF//DTD HTML Strict Level 3//"
-//IETF//DTD HTML Strict//"
-//IETF//DTD HTML//"
-//Metrius//DTD Metrius Presentational//"
-//Microsoft//DTD Internet Explorer 2.0 HTML Strict//"
-//Microsoft//DTD Internet Explorer 2.0 HTML//"
-//Microsoft//DTD Internet Explorer 2.0 Tables//"
-//Microsoft//DTD Internet Explorer 3.0 HTML Strict//"
-//Microsoft//DTD Internet Explorer 3.0 HTML//"
-//Microsoft//DTD Internet Explorer 3.0 Tables//"
-//Netscape Comm. Corp.//DTD HTML//"
-//Netscape Comm. Corp.//DTD Strict HTML//"
-//O'Reilly and Associates//DTD HTML 2.0//"
-//O'Reilly and Associates//DTD HTML Extended 1.0//"
-//O'Reilly and Associates//DTD HTML Extended Relaxed 1.0//"
-//SQ//DTD HTML 2.0 HoTMetaL + extensions//"
-//SoftQuad Software//DTD HoTMetaL PRO 6.0::19990601::extensions to HTML 4.0//"
-//SoftQuad//DTD HoTMetaL PRO 4.0::19971010::extensions to HTML 4.0//"
-//Spyglass//DTD HTML 2.0 Extended//"
-//Sun Microsystems Corp.//DTD HotJava HTML//"
-//Sun Microsystems Corp.//DTD HotJava Strict HTML//"
-//W3C//DTD HTML 3 1995-03-24//"
-//W3C//DTD HTML 3.2 Draft//"
-//W3C//DTD HTML 3.2 Final//"
-//W3C//DTD HTML 3.2//"
-//W3C//DTD HTML 3.2S Draft//"
-//W3C//DTD HTML 4.0 Frameset//"
-//W3C//DTD HTML 4.0 Transitional//"
-//W3C//DTD HTML Experimental 19960712//"
-//W3C//DTD HTML Experimental 970421//"
-//W3C//DTD W3 HTML//"
-//W3O//DTD W3 HTML 3.0//"
-//WebTechs//DTD Mozilla HTML 2.0//"
-//WebTechs//DTD Mozilla HTML//"
-//W3C//DTD HTML 4.01 Frameset//"
-//W3C//DTD HTML 4.01 Transitional//"
Otherwise, if the document is not an iframe
srcdoc
document, and the parser cannot
change
the mode flag is false, and the DOCTYPE token matches one of the conditions in
the
following list, then set the Document to limited-quirks mode:
-//W3C//DTD XHTML 1.0 Frameset//"
-//W3C//DTD XHTML 1.0 Transitional//"
-//W3C//DTD HTML 4.01 Frameset//"
-//W3C//DTD HTML 4.01 Transitional//"
The system identifier and public identifier strings must be compared to the values given in the lists above in an ASCII case-insensitive manner. A system identifier whose value is the empty string is not considered missing for the purposes of the conditions above.
Then, switch the insertion mode to "before html".
If the document is not an iframe
srcdoc
document, then this is a parse
error; if the parser cannot
change the
mode
flag is false, set the
Document to
quirks
mode.
In any case, switch the insertion mode to "before html", then reprocess the token.
When the user agent is to apply the rules for the "before html" insertion mode, the user agent must handle the token as follows:
Parse error. Ignore the token.
Insert a
comment
as the
last child of the Document
object.
Ignore the token.
Create an element
for the
token in the HTML
namespace, with the
Document
as the
intended
parent. Append it to the Document
object.
Put
this element in the stack of open elements.
Switch the insertion mode to "before head".
Act as described in the "anything else" entry below.
Parse error. Ignore the token.
Create an html
element
whose node
document is the Document
object.
Append
it to the Document
object. Put this element in the stack of open
elements.
Switch the insertion mode to "before head", then reprocess the token.
The document
element can end up being removed from the Document
object, e.g. by scripts; nothing in particular happens in such cases, content continues being
appended to the nodes as described in the next section.
When the user agent is to apply the rules for the "before head" insertion mode, the user agent must handle the token as follows:
Ignore the token.
Parse error. Ignore the token.
Process the token using the rules for the "in body" insertion mode.
Insert an HTML element for the token.
Set the head element
pointer
to the
newly created
head
element.
Switch the insertion mode to "in head".
Act as described in the "anything else" entry below.
Parse error. Ignore the token.
Insert an HTML element for a "head" start tag token with no attributes.
Set the head element
pointer to
the newly created
head
element.
Switch the insertion mode to "in head".
Reprocess the current token.
When the user agent is to apply the rules for the "in head" insertion mode, the user agent must handle the token as follows:
Parse error. Ignore the token.
Process the token using the rules for the "in body" insertion mode.
Insert an HTML element for the token. Immediately pop the current node off the stack of open elements.
Acknowledge the token's self-closing flag, if it is set.
Insert an HTML element for the token. Immediately pop the current node off the stack of open elements.
Acknowledge the token's self-closing flag, if it is set.
If the active speculative HTML parser is null, then:
If the element has a charset
attribute, and getting an encoding from
its value results in an encoding,
and
the
confidence is
currently
tentative,
then change the
encoding to the resulting encoding.
Otherwise, if the element has an http-equiv
attribute whose value is an ASCII case-insensitive match for
the
string
"Content-Type", and the element has a content
attribute, and applying the algorithm
for
extracting a character encoding from a meta element to that
attribute's
value returns an encoding,
and
the
confidence is
currently
tentative,
then change
the
encoding to the extracted encoding.
The speculative HTML parser doesn't speculatively apply character encoding declarations in order to reduce implementation complexity.
Follow the generic RCDATA element parsing algorithm.
Follow the generic raw text element parsing algorithm.
Insert an HTML element for the token.
Switch the insertion mode to "in head noscript".
Run these steps:
Let the adjusted insertion location be the appropriate place for inserting a node.
Create an element for the token in the HTML namespace, with the intended parent being the element in which the adjusted insertion location finds itself.
Set the element's parser
document to the Document, and
set the
element's force
async
to false.
This ensures that, if the script is external, any document.write()
calls in the script will execute in-line,
instead of blowing the document away, as would happen in most other cases. It
also
prevents
the script from executing until the end tag is seen.
If the parser was created as part of the HTML fragment parsing
algorithm,
then set the script
element's already
started to
true.
(fragment case)
If the parser was invoked via the document.write()
or document.writeln()
methods, then optionally set the
script
element's already
started
to true. (For example, the user
agent might use this clause to prevent execution of cross-origin
scripts inserted via document.write()
under slow
network conditions, or when the page has already taken a long time to load.)
Insert the newly created element at the adjusted insertion location.
Push the element onto the stack of open elements so that it is the new current node.
Switch the tokenizer to the script data state.
Let the original insertion mode be the current insertion mode.
Switch the insertion mode to "text".
Pop the current node
(which will
be the
head
element)
off the
stack of
open
elements.
Switch the insertion mode to "after head".
Act as described in the "anything else" entry below.
Let template start tag be the start tag.
Insert a marker at the end of the list of active formatting elements.
Set the frameset-ok flag to "not ok".
Switch the insertion mode to "in template".
Push "in template" onto the stack of template insertion modes so that it is the new current template insertion mode.
Let the adjusted insertion location be the appropriate place for inserting a node.
Let intended parent be the element in which the adjusted insertion location finds itself.
Let document be intended parent's node document.
If any of the following are false:
shadowrootmode
is not in
the none state;
then insert an HTML element for the token.
Otherwise:
Let declarative shadow host element be adjusted current node.
Let template be the result of insert a foreign element for template start tag, with HTML namespace and true.
Let mode be template start tag's shadowrootmode
attribute's value.
Let clonable be true if template start tag has a shadowrootclonable
attribute; otherwise
false.
Let serializable be true if template start tag has a shadowrootserializable
attribute;
otherwise false.
Let delegatesFocus be true if template start tag has a
shadowrootdelegatesfocus
attribute;
otherwise false.
If declarative shadow host element is a shadow host, then insert an element at the adjusted insertion location with template.
Otherwise:
Attach a shadow
root with
declarative shadow host element, mode,
clonable,
serializable, delegatesFocus, and
"named".
If an exception is thrown, then catch it and:
Insert an element at the adjusted insertion location with template.
The user agent may report an error to the developer console.
Return.
Let shadow be declarative shadow host element's shadow root.
Set shadow's declarative to true.
Set template's template contents property to shadow.
Set shadow's available to element internals to true.
If there is no template
element on the stack
of
open elements, then
this is a parse error;
ignore
the token.
Otherwise, run these steps:
If the current
node is
not a
template
element, then this is a
parse error.
Pop elements from the stack of open elements
until a
template
element has been popped from the stack.
Pop the current template insertion mode off the stack of template insertion modes.
Parse error. Ignore the token.
Pop the current node
(which will
be the
head
element) off
the
stack of
open
elements.
Switch the insertion mode to "after head".
Reprocess the token.
When the user agent is to apply the rules for the "in head noscript" insertion mode, the user agent must handle the token as follows:
Parse error. Ignore the token.
Process the token using the rules for the "in body" insertion mode.
Pop the current
node (which
will be
a noscript
element) from the
stack of
open
elements; the new current
node will be a
head
element.
Switch the insertion mode to "in head".
Process the token using the rules for the "in head" insertion mode.
Act as described in the "anything else" entry below.
Parse error. Ignore the token.
Pop the current
node
(which will
be a noscript
element) from the
stack of
open
elements; the new current
node will be a
head
element.
Switch the insertion mode to "in head".
Reprocess the token.
When the user agent is to apply the rules for the "after head" insertion mode, the user agent must handle the token as follows:
Parse error. Ignore the token.
Process the token using the rules for the "in body" insertion mode.
Insert an HTML element for the token.
Set the frameset-ok flag to "not ok".
Switch the insertion mode to "in body".
Insert an HTML element for the token.
Switch the insertion mode to "in frameset".
Push the node pointed to by the head element
pointer
onto
the stack of
open elements.
Process the token using the rules for the "in head" insertion mode.
Remove the node pointed to by the head element
pointer
from the stack
of open elements. (It might not be the current node at
this point.)
The head element
pointer cannot
be null at
this point.
Process the token using the rules for the "in head" insertion mode.
Act as described in the "anything else" entry below.
Parse error. Ignore the token.
Insert an HTML element for a "body" start tag token with no attributes.
Switch the insertion mode to "in body".
Reprocess the current token.
When the user agent is to apply the rules for the "in body" insertion mode, the user agent must handle the token as follows:
Parse error. Ignore the token.
Reconstruct the active formatting elements, if any.
Set the frameset-ok flag to "not ok".
Parse error. Ignore the token.
If there is a template
element on the stack
of
open elements, then
ignore the token.
Otherwise, for each attribute on the token, check to see if the attribute is already present on the top element of the stack of open elements. If it is not, add the attribute and its corresponding value to that element.
Process the token using the rules for the "in head" insertion mode.
If the stack of
open
elements has only one node on it, if the second element
on the stack of
open
elements is not a body
element,
or if
there is a
template
element on the stack
of
open elements, then ignore the token.
(fragment case or there
is a
template
element on the stack)
Otherwise, set the frameset-ok
flag to "not ok"; then, for each attribute on the
token, check to see if the attribute is already present on the body
element
(the
second element) on the stack of open elements, and if
it is
not, add
the attribute
and its corresponding value to that element.
If the stack of
open
elements has only one node on it, or if the second element
on the stack of
open
elements is not a body
element,
then
ignore the
token. (fragment case
or there
is a
template
element on the
stack)
If the frameset-ok flag is set to "not ok", ignore the token.
Otherwise, run the following steps:
Remove the second element on the stack of open elements from its parent node, if it has one.
Pop all the nodes from the bottom of the stack of open elements,
from
the
current node up
to, but
not
including, the root html
element.
Insert an HTML element for the token.
Switch the insertion mode to "in frameset".
If the stack of template insertion modes is not empty, then process the token using the rules for the "in template" insertion mode.
Otherwise, follow these steps:
If there is a node in the stack of open elements
that is
not
either a
dd
element, a
dt
element, an
li
element, an
optgroup
element, an option
element, a p
element, an
rb element, an rp
element,
an
rt
element, an
rtc element, a tbody
element, a td
element, a
tfoot
element, a th
element, a thead
element, a
tr
element, the
body
element, or the html
element,
then
this is a parse
error.
If the stack of
open
elements does not have a body element in
scope, this
is a parse error;
ignore the token.
Otherwise, if there is a node in the stack of open elements that is
not
either a
dd
element, a
dt
element, an
li
element, an
optgroup
element, an option
element, a
p
element, an
rb element, an rp
element, an
rt
element, an
rtc element, a tbody
element, a
td
element, a
tfoot
element, a
th
element, a
thead
element, a
tr
element, the
body
element, or the
html
element, then
this is a parse error.
Switch the insertion mode to "after body".
If the stack of
open
elements does not have a body element in
scope, this
is a parse error;
ignore the token.
Otherwise, if there is a node in the stack of open elements that is
not
either a
dd
element, a
dt
element, an
li
element, an
optgroup
element, an option
element, a
p
element, an
rb element, an rp
element, an
rt
element, an
rtc element, a tbody
element, a
td
element, a
tfoot
element, a
th
element, a
thead
element, a
tr
element, the
body
element, or the
html
element, then
this is a parse error.
Switch the insertion mode to "after body".
Reprocess the token.
If the stack of
open
elements has a
p element in button scope, then close a p
element.
Insert an HTML element for the token.
If the stack of
open
elements has a
p element in button scope, then close a p
element.
If the current node is an HTML element whose tag name is one of "h1", "h2", "h3", "h4", "h5", or "h6", then this is a parse error; pop the current node off the stack of open elements.
Insert an HTML element for the token.
If the stack of
open
elements has
a p element in button scope, then close a p
element.
Insert an HTML element for the token.
If the next token is a U+000A
LINE FEED
(LF)
character token, then ignore that
token and move on to the next one. (Newlines at the start of pre
blocks are
ignored
as an authoring convenience.)
Set the frameset-ok flag to "not ok".
If the form
element pointer is not null, and there is
no template
element on the stack of
open elements, then this is a
parse error; ignore the
token.
Otherwise:
If the stack of
open
elements has
a p element in button scope, then close a p
element.
Insert an
HTML
element for the token, and, if there is no template
element on the stack of
open elements, set the form element pointer
to point
to the
element created.
Run these steps:
Set the frameset-ok flag to "not ok".
Initialize node to be the current node (the bottommost node of the stack).
Loop: If node is an li
element, then
run these
substeps:
Generate implied
end
tags,
except for li
elements.
If the current
node is
not an li
element, then this is a
parse
error.
Pop elements from the stack of open
elements
until an
li
element has been popped from the stack.
Jump to the step labeled done below.
If node is in the special
category, but is not an
address,
div,
or
p
element, then
jump to the step
labeled done below.
Otherwise, set node to the previous entry in the stack of open elements and return to the step labeled loop.
Done: If the stack of open elements
has a p
element
in
button scope, then close a
p element.
Finally, insert an HTML element for the token.
Run these steps:
Set the frameset-ok flag to "not ok".
Initialize node to be the current node (the bottommost node of the stack).
Loop: If node is a dd
element, then
run these
substeps:
Generate implied
end
tags,
except for dd
elements.
If the current
node is
not a dd
element, then this is a
parse
error.
Pop elements from the stack of open
elements
until a
dd
element has been popped from the stack.
Jump to the step labeled done below.
If node is a dt
element, then
run these substeps:
Generate implied
end
tags,
except for dt
elements.
If the current
node is
not a dt
element, then this is a
parse
error.
Pop elements from the stack of open
elements
until a
dt
element has been popped from the stack.
Jump to the step labeled done below.
If node is in the special
category, but is not an
address,
div,
or p
element, then
jump to the step
labeled done below.
Otherwise, set node to the previous entry in the stack of open elements and return to the step labeled loop.
Done: If the stack of open elements
has a p
element
in
button scope, then close a
p element.
Finally, insert an HTML element for the token.
If the stack of
open
elements has a
p element in button scope, then close a p
element.
Insert an HTML element for the token.
Switch the tokenizer to the PLAINTEXT state.
Once a start tag with the tag name "plaintext" has been seen, all remaining
tokens will be character tokens (and a final end-of-file token) because there is no way
to
switch the tokenizer out of the PLAINTEXT state. However, as the tree
builder
remains in its existing insertion mode, it might reconstruct the
active
formatting
elements while processing those character tokens. This means that the parser can
insert other elements into the plaintext element.
If the stack
of
open elements has a
button element in scope, then run these substeps:
Pop elements from the stack of open
elements
until a
button
element has been popped from the stack.
Insert an HTML element for the token.
Set the frameset-ok flag to "not ok".
If the stack of open elements does not have an element in scope that is an HTML element with the same tag name as that of the token, then this is a parse error; ignore the token.
Otherwise, run these steps:
If the current node is not an HTML element with the same tag name as that of the token, then this is a parse error.
Pop elements from the stack of open elements until an HTML element with the same tag name as the token has been popped from the stack.
If there is no template
element on the stack of
open elements, then
run these substeps:
Let node be the element that the form
element pointer is set to, or null if it is not set to an element.
Set the form element
pointer
to null.
If node is null or if the stack of open elements does not have node in scope, then this is a parse error; return and ignore the token.
If the current node is not node, then this is a parse error.
Remove node from the stack of open elements.
If there is a template
element on the stack of
open
elements, then run these substeps instead:
If the stack
of
open elements does not have a form
element in
scope, then this is a parse
error; return and ignore the token.
If the current
node is
not a
form
element,
then this is a
parse error.
Pop elements from the stack of open elements
until a
form
element has been popped from the stack.
If the stack of
open
elements does not have a p
element in
button
scope, then this is a parse
error; insert
an HTML element for a "p" start tag token with no
attributes.
If the stack of
open
elements does not have an li
element in
list
item scope, then this is a parse
error; ignore the token.
Otherwise, run these steps:
Generate
implied end tags, except for li
elements.
If the current
node is
not an
li
element,
then this is a
parse error.
Pop elements from the stack of open elements
until an
li
element has been popped from the stack.
If the stack of open elements does not have an element in scope that is an HTML element with the same tag name as that of the token, then this is a parse error; ignore the token.
Otherwise, run these steps:
Generate implied end tags, except for HTML elements with the same tag name as the token.
If the current node is not an HTML element with the same tag name as that of the token, then this is a parse error.
Pop elements from the stack of open elements until an HTML element with the same tag name as the token has been popped from the stack.
If the stack of open elements does not have an element in scope that is an HTML element and whose tag name is one of "h1", "h2", "h3", "h4", "h5", or "h6", then this is a parse error; ignore the token.
Otherwise, run these steps:
If the current node is not an HTML element with the same tag name as that of the token, then this is a parse error.
Pop elements from the stack of open elements until an HTML element whose tag name is one of "h1", "h2", "h3", "h4", "h5", or "h6" has been popped from the stack.
Take a deep breath, then act as described in the "any other end tag" entry below.
If the list of active formatting
elements
contains an a
element
between the end of the list and the last marker on
the list (or the start of the list if there is no marker on the list), then this is
a parse
error; run the adoption agency algorithm for
the
token, then
remove that
element from the list of active
formatting
elements
and the stack
of open
elements if the adoption agency algorithm
didn't
already
remove it (it might
not have if the element is not in table
scope).
In the non-conforming stream
<a href="a">a<table><a href="b">b</table>x, the first
a element
would
be closed
upon seeing the second one, and the "x" character would
be inside a link to "b", not to "a". This is despite the fact that the outer a
element is not in table scope (meaning that a regular </a> end tag at
the start
of the table wouldn't close the outer a element).
The
result is
that the two
a
elements are
indirectly
nested inside each other — non-conforming markup
will often result in non-conforming DOMs when parsed.
Reconstruct the active formatting elements, if any.
Insert an HTML element for the token. Push onto the list of active formatting elements that element.
Reconstruct the active formatting elements, if any.
Insert an HTML element for the token. Push onto the list of active formatting elements that element.
Reconstruct the active formatting elements, if any.
If the stack of
open
elements has a
nobr element in scope, then this is a parse error; run the
adoption
agency
algorithm for the token, then once again reconstruct the
active formatting elements, if any.
Insert an HTML element for the token. Push onto the list of active formatting elements that element.
Run the adoption agency algorithm for the token.
Reconstruct the active formatting elements, if any.
Insert an HTML element for the token.
Insert a marker at the end of the list of active formatting elements.
Set the frameset-ok flag to "not ok".
If the stack of open elements does not have an element in scope that is an HTML element with the same tag name as that of the token, then this is a parse error; ignore the token.
Otherwise, run these steps:
If the current node is not an HTML element with the same tag name as that of the token, then this is a parse error.
Pop elements from the stack of open elements until an HTML element with the same tag name as the token has been popped from the stack.
If the Document is
not set to
quirks mode, and the
stack
of open
elements has a
p element in button scope, then close a p
element.
Insert an HTML element for the token.
Set the frameset-ok flag to "not ok".
Switch the insertion mode to "in table".
Parse error. Drop the attributes from the token, and act as described in the next entry; i.e. act as if this was a "br" start tag token with no attributes, rather than the end tag token that it actually is.
Reconstruct the active formatting elements, if any.
Insert an HTML element for the token. Immediately pop the current node off the stack of open elements.
Acknowledge the token's self-closing flag, if it is set.
Set the frameset-ok flag to "not ok".
Reconstruct the active formatting elements, if any.
Insert an HTML element for the token. Immediately pop the current node off the stack of open elements.
Acknowledge the token's self-closing flag, if it is set.
If the token does not have an attribute with the name "type", or if it does, but that
attribute's value is not an ASCII case-insensitive match for the
string
"hidden", then: set the frameset-ok flag to "not ok".
Insert an HTML element for the token. Immediately pop the current node off the stack of open elements.
Acknowledge the token's self-closing flag, if it is set.
If the stack of
open
elements has a
p element in button scope, then close a p
element.
Insert an HTML element for the token. Immediately pop the current node off the stack of open elements.
Acknowledge the token's self-closing flag, if it is set.
Set the frameset-ok flag to "not ok".
Parse error. Change the token's tag name to "img" and reprocess it. (Don't ask.)
Run these steps:
Insert an HTML element for the token.
If the next token is
a U+000A
LINE
FEED (LF) character token, then ignore
that token and move on to the next one. (Newlines at the start of textarea
elements are ignored as an authoring convenience.)
Switch the tokenizer to the RCDATA state.
Let the original insertion mode be the current insertion mode.
Set the frameset-ok flag to "not ok".
Switch the insertion mode to "text".
If the stack of
open
elements has a
p element in button scope, then close a p
element.
Reconstruct the active formatting elements, if any.
Set the frameset-ok flag to "not ok".
Follow the generic raw text element parsing algorithm.
Set the frameset-ok flag to "not ok".
Follow the generic raw text element parsing algorithm.
Follow the generic raw text element parsing algorithm.
Reconstruct the active formatting elements, if any.
Insert an HTML element for the token.
Set the frameset-ok flag to "not ok".
If the insertion mode is one of "in table", "in caption", "in table body", "in row", or "in cell", then switch the insertion mode to "in select in table". Otherwise, switch the insertion mode to "in select".
If the current node is
an option
element,
then pop the
current node off the stack
of open
elements.
Reconstruct the active formatting elements, if any.
Insert an HTML element for the token.
If the stack of
open
elements has
a
ruby element in scope, then generate implied end tags.
If the
current node is not now
a ruby
element,
this is a
parse error.
Insert an HTML element for the token.
If the stack of
open
elements has
a
ruby element in scope, then generate implied end tags,
except
for rtc elements. If the current node is not
now a
rtc
element or a ruby
element, this is a parse
error.
Insert an HTML element for the token.
Reconstruct the active formatting elements, if any.
Adjust MathML attributes for the token. (This fixes the case of MathML attributes that are not all lowercase.)
Adjust foreign attributes for the token. (This fixes the use of namespaced attributes, in particular XLink.)
Insert a foreign element for the token, with MathML namespace and false.
If the token has its self-closing flag set, pop the current node off the stack of open elements and acknowledge the token's self-closing flag.
Reconstruct the active formatting elements, if any.
Adjust SVG attributes for the token. (This fixes the case of SVG attributes that are not all lowercase.)
Adjust foreign attributes for the token. (This fixes the use of namespaced attributes, in particular XLink in SVG.)
Insert a foreign element for the token, with SVG namespace and false.
If the token has its self-closing flag set, pop the current node off the stack of open elements and acknowledge the token's self-closing flag.
Parse error. Ignore the token.
Reconstruct the active formatting elements, if any.
Insert an HTML element for the token.
This element will be an ordinary
element. With one exception: if
the scripting flag
is
disabled, it
can also be a noscript
element.
Run these steps:
Initialize node to be the current node (the bottommost node of the stack).
Loop: If node is an HTML element with the same tag name as the token, then:
Generate implied end tags, except for HTML elements with the same tag name as the token.
If node is not the current node, then this is a parse error.
Pop all the nodes from the current node up to node, including node, then stop these steps.
Otherwise, if node is in the special category, then this is a parse error; ignore the token, and return.
Set node to the previous entry in the stack of open elements.
Return to the step labeled loop.
When the steps above say the user agent is to close a p
element, it
means that the user agent must run the following steps:
Generate
implied
end tags, except for p elements.
If the current node is
not a
p
element, then
this is a
parse error.
Pop elements from the stack of open elements until a
p element
has been popped from the stack.
The adoption agency algorithm, which takes as its only argument a token token for which the algorithm is being run, consists of the following steps:
Let subject be token's tag name.
If the current node is an HTML element whose tag name is subject, and the current node is not in the list of active formatting elements, then pop the current node off the stack of open elements and return.
Let outerLoopCounter be 0.
While true:
If outerLoopCounter is greater than or equal to 8, then return.
Increment outerLoopCounter by 1.
Let formattingElement be the last element in the list of active formatting elements that:
If there is no such element, then return and instead act as described in the "any other end tag" entry above.
If formattingElement is not in the stack of open elements, then this is a parse error; remove the element from the list, and return.
If formattingElement is in the stack of open elements, but the element is not in scope, then this is a parse error; return.
If formattingElement is not the current node, this is a parse error. (But do not return.)
Let furthestBlock be the topmost node in the stack of open elements that is lower in the stack than formattingElement, and is an element in the special category. There might not be one.
If there is no furthestBlock, then the UA must first pop all the nodes from the bottom of the stack of open elements, from the current node up to and including formattingElement, then remove formattingElement from the list of active formatting elements, and finally return.
Let commonAncestor be the element immediately above formattingElement in the stack of open elements.
Let a bookmark note the position of formattingElement in the list of active formatting elements relative to the elements on either side of it in the list.
Let node and lastNode be furthestBlock.
Let innerLoopCounter be 0.
While true:
Increment innerLoopCounter by 1.
Let node be the element immediately above node in the stack of open elements, or if node is no longer in the stack of open elements (e.g. because it got removed by this algorithm), the element that was immediately above node in the stack of open elements before node was removed.
If node is formattingElement, then break.
If innerLoopCounter is greater than 3 and node is in the list of active formatting elements, then remove node from the list of active formatting elements.
If node is not in the list of active formatting elements, then remove node from the stack of open elements and continue.
Create an element for the token for which the element node was created, in the HTML namespace, with commonAncestor as the intended parent; replace the entry for node in the list of active formatting elements with an entry for the new element, replace the entry for node in the stack of open elements with an entry for the new element, and let node be the new element.
If last node is furthestBlock, then move the aforementioned bookmark to be immediately after the new node in the list of active formatting elements.
Append lastNode to node.
Set lastNode to node.
Insert whatever lastNode ended up being in the previous step at the appropriate place for inserting a node, but using commonAncestor as the override target.
Create an element for the token for which formattingElement was created, in the HTML namespace, with furthestBlock as the intended parent.
Take all of the child nodes of furthestBlock and append them to the element created in the last step.
Append that new element to furthestBlock.
Remove formattingElement from the list of active formatting elements, and insert the new element into the list of active formatting elements at the position of the aforementioned bookmark.
Remove formattingElement from the stack of open elements, and insert the new element into the stack of open elements immediately below the position of furthestBlock in that stack.
This algorithm's name, the "adoption agency algorithm", comes from the way it causes elements to change parents, and is in contrast with other possible algorithms for dealing with misnested content.
When the user agent is to apply the rules for the "text" insertion mode, the user agent must handle the token as follows:
This can never be a U+0000 NULL character; the tokenizer converts those to U+FFFD REPLACEMENT CHARACTER characters.
If the current node is a
script
element,
then set its already
started to true.
Pop the current node off the stack of open elements.
Switch the insertion mode to the original insertion mode and reprocess the token.
If the active speculative HTML parser is null and the JavaScript execution context stack is empty, then perform a microtask checkpoint.
Let script be the current
node (which will be a
script
element).
Pop the current node off the stack of open elements.
Switch the insertion mode to the original insertion mode.
Let the old insertion point have the same value as the current insertion point. Let the insertion point be just before the next input character.
Increment the parser's script nesting level by one.
If the active speculative HTML parser is null, then prepare the script element script. This might cause some script to execute, which might cause new characters to be inserted into the tokenizer, and might cause the tokenizer to output more tokens, resulting in a reentrant invocation of the parser.
Decrement the parser's script nesting level by one. If the parser's script nesting level is zero, then set the parser pause flag to false.
Let the insertion point have the value of the old insertion point. (In other words, restore the insertion point to its previous value. This value might be the "undefined" value.)
At this stage, if the pending parsing-blocking script is not null, then:
Set the parser pause flag to true, and abort the processing of any nested invocations of the tokenizer, yielding control back to the caller. (Tokenization will resume when the caller returns to the "outer" tree construction stage.)
The tree construction stage of this particular parser is being
called reentrantly, say from a call to document.write().
While the pending parsing-blocking script is not null:
Let the script be the pending parsing-blocking script.
Set the pending parsing-blocking script to null.
Start the speculative HTML parser for this instance of the HTML parser.
Block the tokenizer for this instance of the HTML parser, such that the event loop will not run tasks that invoke the tokenizer.
If the parser's Document
has
a
style sheet
that is blocking
scripts or the script's ready to be
parser-executed
is false:
spin
the event
loop until the parser's Document
has
no
style
sheet that is blocking scripts and the script's ready to be
parser-executed becomes true.
If this parser has been aborted in the meantime, return.
This could happen if, e.g., while the spin the event
loop
algorithm is running, the Document
gets destroyed,
or the document.open()
method gets invoked on the Document.
Stop the speculative HTML parser for this instance of the HTML parser.
Unblock the tokenizer for this instance of the HTML parser, such that tasks that invoke the tokenizer can again be run.
Let the insertion point be just before the next input character.
Increment the parser's script nesting level by one (it should be zero before this step, so this sets it to one).
Execute the script element the script.
Decrement the parser's script nesting level by one. If the parser's script nesting level is zero (which it always should be at this point), then set the parser pause flag to false.
Let the insertion point be undefined again.
Pop the current node off the stack of open elements.
Switch the insertion mode to the original insertion mode.
When the user agent is to apply the rules for the "in table" insertion mode, the user agent must handle the token as follows:
table,
tbody,
template,
tfoot,
thead,
or tr
element
Let the pending table character tokens be an empty list of tokens.
Let the original insertion mode be the current insertion mode.
Switch the insertion mode to "in table text" and reprocess the token.
Parse error. Ignore the token.
Clear the stack back to a table context. (See below.)
Insert a marker at the end of the list of active formatting elements.
Insert an HTML element for the token, then switch the insertion mode to "in caption".
Clear the stack back to a table context. (See below.)
Insert an HTML element for the token, then switch the insertion mode to "in column group".
Clear the stack back to a table context. (See below.)
Insert an HTML element for a "colgroup" start tag token with no attributes, then switch the insertion mode to "in column group".
Reprocess the current token.
Clear the stack back to a table context. (See below.)
Insert an HTML element for the token, then switch the insertion mode to "in table body".
Clear the stack back to a table context. (See below.)
Insert an HTML element for a "tbody" start tag token with no attributes, then switch the insertion mode to "in table body".
Reprocess the current token.
If the stack of
open
elements does not have a table
element in
table
scope, ignore the token.
Otherwise:
Pop elements from this stack until a table
element has
been popped from the
stack.
Reset the insertion mode appropriately.
Reprocess the token.
If the stack of
open
elements does not have a table
element in
table
scope, this is a parse
error; ignore the token.
Otherwise:
Pop elements from this stack until a table
element has
been popped from the
stack.
Parse error. Ignore the token.
Process the token using the rules for the "in head" insertion mode.
If the token does not have an attribute with the name "type", or if it does, but that
attribute's value is not an ASCII case-insensitive match for the
string
"hidden", then: act as described in the "anything else" entry below.
Otherwise:
Insert an HTML element for the token.
Pop that input
element off the stack
of open elements.
Acknowledge the token's self-closing flag, if it is set.
If there is a template
element on the stack of
open elements, or if
the form
element
pointer is not null, ignore the
token.
Otherwise:
Insert
an HTML
element for the token, and set the form element pointer
to
point to the
element created.
Pop that form
element
off the stack
of open
elements.
Process the token using the rules for the "in body" insertion mode.
Parse error. Enable foster parenting, process the token using the rules for the "in body" insertion mode, and then disable foster parenting.
When the steps above require the UA to clear the
stack
back to a
table context, it
means that the UA must, while the current
node
is not a table,
template,
or html
element, pop
elements
from the stack
of open
elements.
This is the same list of elements as used in the has an element in table scope steps.
The current node
being an
html
element after
this
process is a fragment case.
When the user agent is to apply the rules for the "in table text" insertion mode, the user agent must handle the token as follows:
Parse error. Ignore the token.
Append the character token to the pending table character tokens list.
If any of the tokens in the pending table character tokens list are character tokens that are not ASCII whitespace, then this is a parse error: reprocess the character tokens in the pending table character tokens list using the rules given in the "anything else" entry in the "in table" insertion mode.
Otherwise, insert the characters given by the pending table character tokens list.
Switch the insertion mode to the original insertion mode and reprocess the token.
When the user agent is to apply the rules for the "in caption" insertion mode, the user agent must handle the token as follows:
If the stack of
open
elements does not have a caption
element
in table
scope, this is a parse
error; ignore the token. (fragment case)
Otherwise:
Now, if the current node
is not
a caption
element, then this is a
parse error.
Pop elements from this stack until a caption
element has been popped from the
stack.
Clear the list of active formatting elements up to the last marker.
Switch the insertion mode to "in table".
If the stack
of open
elements does not have a
caption
element in
table scope, this is a parse
error; ignore the token. (fragment case)
Otherwise:
Now, if the current
node is
not a
caption
element, then this is a
parse error.
Pop elements from this stack until a caption
element has been popped from the
stack.
Clear the list of active formatting elements up to the last marker.
Switch the insertion mode to "in table".
Reprocess the token.
Parse error. Ignore the token.
Process the token using the rules for the "in body" insertion mode.
When the user agent is to apply the rules for the "in column group" insertion mode, the user agent must handle the token as follows:
Parse error. Ignore the token.
Process the token using the rules for the "in body" insertion mode.
Insert an HTML element for the token. Immediately pop the current node off the stack of open elements.
Acknowledge the token's self-closing flag, if it is set.
If the current node
is not a
colgroup
element, then this is a
parse error; ignore
the
token.
Otherwise, pop the current node from the stack of open elements. Switch the insertion mode to "in table".
Parse error. Ignore the token.
Process the token using the rules for the "in head" insertion mode.
Process the token using the rules for the "in body" insertion mode.
If the current node
is not a
colgroup
element, then this is a
parse error; ignore
the
token.
Otherwise, pop the current node from the stack of open elements.
Switch the insertion mode to "in table".
Reprocess the token.
When the user agent is to apply the rules for the "in table body" insertion mode, the user agent must handle the token as follows:
Clear the stack back to a table body context. (See below.)
Insert an HTML element for the token, then switch the insertion mode to "in row".
Clear the stack back to a table body context. (See below.)
Insert an HTML element for a "tr" start tag token with no attributes, then switch the insertion mode to "in row".
Reprocess the current token.
If the stack of open elements does not have an element in table scope that is an HTML element with the same tag name as the token, this is a parse error; ignore the token.
Otherwise:
Clear the stack back to a table body context. (See below.)
Pop the current node from the stack of open elements. Switch the insertion mode to "in table".
If the stack of
open
elements does not have a tbody,
thead, or tfoot element in table
scope, this is a parse
error;
ignore the token.
Otherwise:
Clear the stack back to a table body context. (See below.)
Pop the current node from the stack of open elements. Switch the insertion mode to "in table".
Reprocess the token.
Parse error. Ignore the token.
Process the token using the rules for the "in table" insertion mode.
When the steps above require the UA to clear
the
stack back
to a table body context,
it means that the UA must, while the current
node is not a tbody,
tfoot,
thead,
template,
or
html
element, pop
elements from the stack
of open
elements.
The current node
being an
html
element after
this
process is a fragment case.
When the user agent is to apply the rules for the "in row" insertion mode, the user agent must handle the token as follows:
Clear the stack back to a table row context. (See below.)
Insert an HTML element for the token, then switch the insertion mode to "in cell".
Insert a marker at the end of the list of active formatting elements.
If the stack
of open
elements does not have a tr element in
table
scope, this is a parse
error;
ignore the token.
Otherwise:
Clear the stack back to a table row context. (See below.)
Pop the current node (which
will be a
tr element)
from
the
stack of
open
elements. Switch the insertion
mode to "in
table
body".
If the stack of
open
elements does not have a tr element
in table
scope, this is a parse
error;
ignore the token.
Otherwise:
Clear the stack back to a table row context. (See below.)
Pop the current node (which
will be
a tr
element)
from the
stack of
open
elements. Switch the insertion
mode to "in
table
body".
Reprocess the token.
If the stack of open elements does not have an element in table scope that is an HTML element with the same tag name as the token, this is a parse error; ignore the token.
If the stack of
open
elements does not have a tr element
in table
scope, ignore the token.
Otherwise:
Clear the stack back to a table row context. (See below.)
Pop the current node (which
will be
a tr
element)
from the
stack of
open
elements. Switch the insertion
mode to "in
table
body".
Reprocess the token.
Parse error. Ignore the token.
Process the token using the rules for the "in table" insertion mode.
When the steps above require the UA to clear
the
stack back
to a table row context,
it means that the UA must, while the current
node
is not a tr,
template,
or
html element,
pop
elements from
the stack of open
elements.
The current node being
an html
element after this
process is a fragment case.
When the user agent is to apply the rules for the "in cell" insertion mode, the user agent must handle the token as follows:
If the stack of open elements does not have an element in table scope that is an HTML element with the same tag name as that of the token, then this is a parse error; ignore the token.
Otherwise:
Now, if the current node is not an HTML element with the same tag name as the token, then this is a parse error.
Pop elements from the stack of open elements until an HTML element with the same tag name as the token has been popped from the stack.
Clear the list of active formatting elements up to the last marker.
Switch the insertion mode to "in row".
Assert: The stack of open elements has
a
td or th element in table scope.
Close the cell (see below) and reprocess the token.
Parse error. Ignore the token.
If the stack of open elements does not have an element in table scope that is an HTML element with the same tag name as that of the token, then this is a parse error; ignore the token.
Otherwise, close the cell (see below) and reprocess the token.
Process the token using the rules for the "in body" insertion mode.
Where the steps above say to close the cell, they mean to run the following algorithm:
If the current node is not
now a
td element
or a
th
element, then this is a parse
error.
Pop elements from the stack
of open elements until a td
element or a th
element
has been popped from the stack.
Clear the list of active formatting elements up to the last marker.
Switch the insertion mode to "in row".
The stack of
open
elements cannot have both a td and a
th element in
table
scope
at the
same time, nor can it have neither when the close
the cell algorithm is invoked.
When the user agent is to apply the rules for the "in select" insertion mode, the user agent must handle the token as follows:
Parse error. Ignore the token.
Parse error. Ignore the token.
Process the token using the rules for the "in body" insertion mode.
If the current node is an
option
element,
pop that node from the
stack of
open
elements.
Insert an HTML element for the token.
If the current node is
an option
element,
pop that node from the
stack
of open
elements.
If the current node is
an optgroup
element, pop that node from the
stack
of open
elements.
Insert an HTML element for the token.
If the current node is
an option
element,
pop that node from the
stack
of open
elements.
If the current node is
an optgroup
element, pop that node from the
stack
of open
elements.
Insert an HTML element for the token. Immediately pop the current node off the stack of open elements.
Acknowledge the token's self-closing flag, if it is set.
First, if the current
node is
an option
element,
and the node
immediately before it in the stack of open elements is an
optgroup
element, then pop the current
node
from the stack
of open
elements.
If the current node is
an optgroup
element, then pop that node from
the stack of
open
elements. Otherwise, this is a parse error; ignore
the token.
If the current node is
an
option
element,
then pop that node from
the stack of
open
elements. Otherwise, this is a parse error; ignore
the token.
If the stack
of open
elements does not have a select
element
in select
scope, this is a parse
error; ignore the token. (fragment
case)
Otherwise:
Pop elements from the stack of open elements until
a select
element
has been popped from the stack.
If the stack
of open
elements does not have a select
element
in
select scope, ignore the token.
(fragment case)
Otherwise:
Pop elements from the stack of open elements until
a select
element
has been popped from the stack.
Reset the insertion mode appropriately.
It just gets treated like an end tag.
If the stack
of open
elements does not have a select
element
in
select scope, ignore the token.
(fragment case)
Otherwise:
Pop elements from the stack of open elements until
a select
element
has been popped from the stack.
Reset the insertion mode appropriately.
Reprocess the token.
Process the token using the rules for the "in head" insertion mode.
Process the token using the rules for the "in body" insertion mode.
Parse error. Ignore the token.
When the user agent is to apply the rules for the "in select in table" insertion mode, the user agent must handle the token as follows:
Pop elements from the stack of open elements
until a
select
element
has been popped from the stack.
Reset the insertion mode appropriately.
Reprocess the token.
If the stack of open elements does not have an element in table scope that is an HTML element with the same tag name as that of the token, then ignore the token.
Otherwise:
Pop elements from the stack of open elements
until a
select
element
has been popped from the stack.
Reset the insertion mode appropriately.
Reprocess the token.
Process the token using the rules for the "in select" insertion mode.
When the user agent is to apply the rules for the "in template" insertion mode, the user agent must handle the token as follows:
Process the token using the rules for the "in body" insertion mode.
Process the token using the rules for the "in head" insertion mode.
Pop the current template insertion mode off the stack of template insertion modes.
Push "in table" onto the stack of template insertion modes so that it is the new current template insertion mode.
Switch the insertion mode to "in table", and reprocess the token.
Pop the current template insertion mode off the stack of template insertion modes.
Push "in column group" onto the stack of template insertion modes so that it is the new current template insertion mode.
Switch the insertion mode to "in column group", and reprocess the token.
Pop the current template insertion mode off the stack of template insertion modes.
Push "in table body" onto the stack of template insertion modes so that it is the new current template insertion mode.
Switch the insertion mode to "in table body", and reprocess the token.
Pop the current template insertion mode off the stack of template insertion modes.
Push "in row" onto the stack of template insertion modes so that it is the new current template insertion mode.
Switch the insertion mode to "in row", and reprocess the token.
Pop the current template insertion mode off the stack of template insertion modes.
Push "in body" onto the stack of template insertion modes so that it is the new current template insertion mode.
Switch the insertion mode to "in body", and reprocess the token.
Parse error. Ignore the token.
If there is no template
element on the stack
of open elements, then
stop parsing. (fragment case)
Otherwise, this is a parse error.
Pop elements from the stack of open elements until
a template
element has been popped from the stack.
Clear the list of active formatting elements up to the last marker.
Pop the current template insertion mode off the stack of template insertion modes.
Reset the insertion mode appropriately.
Reprocess the token.
When the user agent is to apply the rules for the "after body" insertion mode, the user agent must handle the token as follows:
Process the token using the rules for the "in body" insertion mode.
Insert a comment
as the
last
child of the first element in the stack of
open elements (the html
element).
Parse error. Ignore the token.
Process the token using the rules for the "in body" insertion mode.
If the parser was created as part of the HTML fragment parsing algorithm, this is a parse error; ignore the token. (fragment case)
Otherwise, switch the insertion mode to "after after body".
Parse error. Switch the insertion mode to "in body" and reprocess the token.
When the user agent is to apply the rules for the "in frameset" insertion mode, the user agent must handle the token as follows:
Parse error. Ignore the token.
Process the token using the rules for the "in body" insertion mode.
Insert an HTML element for the token.
If the current node is
the root
html
element, then
this is a
parse error; ignore
the
token. (fragment
case)
Otherwise, pop the current node from the stack of open elements.
If the parser was not created as part of the HTML fragment parsing
algorithm
(fragment case),
and the
current node is no
longer a
frameset element,
then
switch the
insertion mode
to "after
frameset".
Insert an HTML element for the token. Immediately pop the current node off the stack of open elements.
Acknowledge the token's self-closing flag, if it is set.
Process the token using the rules for the "in head" insertion mode.
If the current node
is not
the root
html
element,
then this is a
parse error.
The current
node
can only
be the root
html
element in
the fragment case.
Parse error. Ignore the token.
When the user agent is to apply the rules for the "after frameset" insertion mode, the user agent must handle the token as follows:
Parse error. Ignore the token.
Process the token using the rules for the "in body" insertion mode.
Switch the insertion mode to "after after frameset".
Process the token using the rules for the "in head" insertion mode.
Parse error. Ignore the token.
When the user agent is to apply the rules for the "after after body" insertion mode, the user agent must handle the token as follows:
Insert
a
comment as
the last child of the Document
object.
Process the token using the rules for the "in body" insertion mode.
Parse error. Switch the insertion mode to "in body" and reprocess the token.
When the user agent is to apply the rules for the "after after frameset" insertion mode, the user agent must handle the token as follows:
Insert a
comment as the last child of the Document
object.
Process the token using the rules for the "in body" insertion mode.
Process the token using the rules for the "in head" insertion mode.
Parse error. Ignore the token.
When the user agent is to apply the rules for parsing tokens in foreign content, the user agent must handle the token as follows:
Parse error. Insert a U+FFFD REPLACEMENT CHARACTER character.
Set the frameset-ok flag to "not ok".
Parse error. Ignore the token.
While the current node is not a MathML text integration point, an HTML integration point, or an element in the HTML namespace, pop elements from the stack of open elements.
Reprocess the token according to the rules given in the section corresponding to the current insertion mode in HTML content.
If the adjusted current node is an element in the MathML namespace, adjust MathML attributes for the token. (This fixes the case of MathML attributes that are not all lowercase.)
If the adjusted current node is an element in the SVG namespace, and the token's tag name is one of the ones in the first column of the following table, change the tag name to the name given in the corresponding cell in the second column. (This fixes the case of SVG elements that are not all lowercase.)
| Tag name | Element name |
|---|---|
altglyph
| altGlyph
|
altglyphdef
| altGlyphDef
|
altglyphitem
| altGlyphItem
|
animatecolor
| animateColor
|
animatemotion
| animateMotion
|
animatetransform
| animateTransform
|
clippath
| clipPath
|
feblend
| feBlend
|
fecolormatrix
| feColorMatrix
|
fecomponenttransfer
| feComponentTransfer
|
fecomposite
| feComposite
|
feconvolvematrix
| feConvolveMatrix
|
fediffuselighting
| feDiffuseLighting
|
fedisplacementmap
| feDisplacementMap
|
fedistantlight
| feDistantLight
|
fedropshadow
| feDropShadow
|
feflood
| feFlood
|
fefunca
| feFuncA
|
fefuncb
| feFuncB
|
fefuncg
| feFuncG
|
fefuncr
| feFuncR
|
fegaussianblur
| feGaussianBlur
|
feimage
| feImage
|
femerge
| feMerge
|
femergenode
| feMergeNode
|
femorphology
| feMorphology
|
feoffset
| feOffset
|
fepointlight
| fePointLight
|
fespecularlighting
| feSpecularLighting
|
fespotlight
| feSpotLight
|
fetile
| feTile
|
feturbulence
| feTurbulence
|
foreignobject
| foreignObject
|
glyphref
| glyphRef
|
lineargradient
| linearGradient
|
radialgradient
| radialGradient
|
textpath
| textPath
|
If the adjusted current node is an element in the SVG namespace, adjust SVG attributes for the token. (This fixes the case of SVG attributes that are not all lowercase.)
Adjust foreign attributes for the token. (This fixes the use of namespaced attributes, in particular XLink in SVG.)
Insert a foreign element for the token, with adjusted current node's namespace and false.
If the token has its self-closing flag set, then run the appropriate steps from the following list:
Acknowledge the token's self-closing flag, and then act as described in the steps for a "script" end tag below.
Pop the current node off the stack of open elements and acknowledge the token's self-closing flag.
script element
Pop the current node off the stack of open elements.
Let the old insertion point have the same value as the current insertion point. Let the insertion point be just before the next input character.
Increment the parser's script nesting level by one. Set the parser pause flag to true.
If the active speculative HTML
parser
is null
and the user agent supports SVG,
then Process
the
SVG script element according to the SVG rules. [SVG]
Even if this causes new characters to be inserted into the tokenizer, the parser will not be executed reentrantly, since the parser pause flag is true.
Decrement the parser's script nesting level by one. If the parser's script nesting level is zero, then set the parser pause flag to false.
Let the insertion point have the value of the old insertion point. (In other words, restore the insertion point to its previous value. This value might be the "undefined" value.)
Run these steps:
Initialize node to be the current node (the bottommost node of the stack).
If node's tag name, converted to ASCII lowercase, is not the same as the tag name of the token, then this is a parse error.
Loop: If node is the topmost element in the stack of open elements, then return. (fragment case)
If node's tag name, converted to ASCII lowercase, is the same as the tag name of the token, pop elements from the stack of open elements until node has been popped from the stack, and then return.
Set node to the previous entry in the stack of open elements.
If node is not an element in the HTML namespace, return to the step labeled loop.
Otherwise, process the token according to the rules given in the section corresponding to the current insertion mode in HTML content.
Document/DOMContentLoaded_event
Support in all current engines.
Once the user agent stops parsing the document, the user agent must run the following steps:
Support in all current engines.
If the active speculative HTML parser is not null, then stop the speculative HTML parser and return.
Set the insertion point to undefined.
Update
the current document readiness to "interactive".
Pop all the nodes off the stack of open elements.
While the list of scripts that will execute when the document has finished parsing is not empty:
Spin the event
loop until
the
first script
in the
list
of scripts that will execute when the document has finished parsing has
its ready
to be parser-executed set to true and the parser's Document
has no style sheet
that is
blocking
scripts.
Execute
the
script
element given by the first script
in
the list
of scripts that will execute when the document has finished
parsing.
Remove the first script
element from
the list
of scripts that will
execute when the document has finished parsing (i.e. shift out the first
entry
in the
list).
Queue a global task on
the DOM
manipulation
task
source given the
Document's relevant global
object
to run the following substeps:
Set the Document's load timing info's DOM
content loaded
event start time to the current high resolution
time given
the
Document's relevant
global
object.
Fire an
event named DOMContentLoaded
at the Document
object, with its bubbles
attribute initialized to
true.
Set the Document's load timing info's
DOM
content loaded
event end time to the current high resolution
time given
the
Document's relevant
global
object.
Enable the client
message
queue of the
ServiceWorkerContainer
object whose associated service worker
client is
the
Document object's relevant
settings
object.
Invoke WebDriver BiDi DOM content
loaded with
the Document's
browsing
context, and a
new WebDriver BiDi
navigation status whose id
is the
Document object's during-loading
navigation ID for WebDriver BiDi, status
is "pending",
and url is
the Document object's
URL.
Spin the event loop until the set of scripts that will execute as soon as possible and the list of scripts that will execute in order as soon as possible are empty.
Spin the event loop
until there
is
nothing that delays the load event in the Document.
Queue a global task on
the DOM
manipulation task
source given the
Document's relevant global
object to run the following steps:
Update the current
document
readiness
to "complete".
If the Document
object's browsing
context is null, then abort these steps.
Let window be the Document's
relevant
global
object.
Set the Document's load timing info's
load event start
time to the current high resolution
time given
window.
Fire an
event named load at
window, with
legacy target override
flag set.
Invoke WebDriver BiDi load
complete with
the Document's browsing
context, and
a new WebDriver BiDi
navigation status whose id is the
Document object's during-loading
navigation ID for WebDriver BiDi, status
is "complete",
and url is
the
Document object's URL.
Set the Document
object's during-loading navigation ID for
WebDriver
BiDi
to null.
Set the Document's load timing info's
load event end
time to the current high resolution
time given
window.
Assert: Document's page showing is
false.
Set the Document's page showing flag to true.
Fire a page
transition event named pageshow at
window
with false.
If the Document's print when loaded flag is
set, then
run the
printing steps.
The Document is now ready for post-load tasks.
When the user agent is to abort a parser, it must run the following steps:
Throw away any pending content in the input stream, and discard any future content that would have been added to it.
Stop the speculative HTML parser for this HTML parser.
Update
the current document readiness to "interactive".
Pop all the nodes off the stack of open elements.
Update
the current document readiness to "complete".
User agents may implement an optimization, as described in this section, to speculatively fetch resources that are declared in the HTML markup while the HTML parser is waiting for a pending parsing-blocking script to be fetched and executed, or during normal parsing, at the time an element is created for a token. While this optimization is not defined in precise detail, there are some rules to consider for interoperability.
Each HTML parser can have an active speculative HTML parser. It is initially null.
The speculative HTML parser must act like the normal HTML parser (e.g., the tree builder rules apply), with some exceptions:
The state of the normal HTML parser and the document itself must not be affected.
For example, the next input character or the stack of open elements for the normal HTML parser is not affected by the speculative HTML parser.
Bytes pushed into the HTML parser's input byte stream must also be pushed into the speculative HTML parser's input byte stream. Bytes read from the streams must be independent.
The result of the speculative parsing is primarily a series of speculative fetches. Which kinds of resources to speculatively fetch is implementation-defined, but user agents must not speculatively fetch resources that would not be fetched with the normal HTML parser, under the assumption that the script that is blocking the HTML parser does nothing.
It is possible that the same markup is seen multiple times from the speculative HTML parser and then the normal HTML parser. It is expected that duplicated fetches will be prevented by caching rules, which are not yet fully specified.
A speculative fetch for a speculative mock element element must follow these rules:
Should some of these things be applied to the document "for real", even though they are found speculatively?
If the speculative HTML parser encounters one of the following elements, then act as if that element is processed for the purpose of its effect of subsequent speculative fetches.
base
element.
meta
element whose http-equiv
attribute is in the Content
security policy state.
meta
element whose name
attribute is
an
ASCII case-insensitive match for
"referrer".
meta
element whose name
attribute
is an
ASCII case-insensitive match for
"viewport". (This can
affect whether a media query list matches the
environment.) [CSSDEVICEADAPT]
Let url be the URL that element would fetch if it was processed normally. If there is no such URL or if it is the empty string, then do nothing. Otherwise, if url is already in the list of speculative fetch URLs, then do nothing. Otherwise, fetch url as if the element was processed normally, and add url to the list of speculative fetch URLs.
Each Document has a list of speculative fetch URLs, which is a
list
of URLs, initially empty.
To start the speculative HTML parser for an instance of an HTML parser parser:
Optionally, return.
This step allows user agents to opt out of speculative HTML parsing.
If parser's active speculative HTML parser is not null, then stop the speculative HTML parser for parser.
This can happen when document.write()
writes another parser-blocking script. For simplicity, this specification always
restarts
speculative parsing, but user agents can implement a more efficient strategy, so long as
the end
result is equivalent.
Let speculativeParser be a new speculative HTML parser, with the same state as parser.
Let speculativeDoc be a new isomorphic representation of parser's
Document,
where all
elements
are instead speculative mock
elements. Let
speculativeParser parse into
speculativeDoc.
Set parser's active speculative HTML parser to speculativeParser.
In parallel, run speculativeParser until it is stopped or until it reaches the end of its input stream.
To stop the speculative HTML parser for an instance of an HTML parser parser:
Let speculativeParser be parser's active speculative HTML parser.
If speculativeParser is null, then return.
Throw away any pending content in speculativeParser's input stream, and discard any future content that would have been added to it.
Set parser's active speculative HTML parser to null.
The speculative HTML parser will create speculative mock elements instead of normal elements. DOM operations that the tree builder normally does on elements are expected to work appropriately on speculative mock elements.
A speculative mock element is a struct with the following items:
A string namespace, corresponding to an element's namespace.
A string local name, corresponding to an element's local name.
A list attribute list, corresponding to an element's attribute list.
To create a speculative mock element given a namespace, tagName, and attributes:
Let element be a new speculative mock element.
Set element's namespace to namespace.
Set element's local name to tagName.
Set element's attribute list to attributes.
Optionally, perform a speculative fetch for element.
Return element.
When the tree builder says to insert an element into a template
element's
template contents,
if that
is a speculative
mock
element, and the
template
element's template
contents is
not a
ShadowRoot
node, instead do nothing. URLs found speculatively inside
non-declarative-shadow-root template
elements might themselves be templates, and must
not be speculatively fetched.
When an application uses an HTML
parser in conjunction with an XML pipeline, it is
possible that the constructed DOM is not compatible with the XML tool chain in certain subtle
ways. For example, an XML toolchain might not be able to represent attributes with the name
xmlns,
since they conflict with the Namespaces in XML syntax. There is also some
data that the HTML
parser
generates that isn't included in the DOM itself. This
section specifies some rules for handling these issues.
If the XML API being used doesn't support DOCTYPEs, the tool may drop DOCTYPEs altogether.
If the XML API doesn't support attributes in no namespace that are named "xmlns",
attributes
whose
names start with "xmlns:", or
attributes in the XMLNS
namespace,
then the tool may drop such attributes.
The tool may annotate the output with any namespace declarations required for proper operation.
If the XML API being used restricts the allowable characters in the local names of elements and attributes, then the tool may map all element and attribute local names that the API wouldn't support to a set of names that are allowed, by replacing any character that isn't supported with the uppercase letter U and the six digits of the character's code point when expressed in hexadecimal, using digits 0-9 and capital letters A-F as the symbols, in increasing numeric order.
For example, the element name foo<bar, which can be
output by the HTML
parser, though
it is neither a legal HTML element name nor a
well-formed XML element name, would be converted into fooU00003Cbar, which
is a well-formed XML element name (though it's still not legal in HTML by any means).
As another example, consider the attribute xlink:href.
Used on a MathML element, it becomes, after being adjusted, an attribute
with a
prefix
"xlink" and a local
name "href". However, used on an HTML element, it becomes an attribute with
no prefix and the local name "xlink:href", which is not a valid NCName, and
thus might not be accepted by an XML API. It could thus get converted, becoming
"xlinkU00003Ahref".
The resulting names from this conversion conveniently can't clash with any attribute generated by the HTML parser, since those are all either lowercase or those listed in the adjust foreign attributes algorithm's table.
If the XML API restricts comments from having two consecutive U+002D HYPHEN-MINUS characters (--), the tool may insert a single U+0020 SPACE character between any such offending characters.
If the XML API restricts comments from ending in a U+002D HYPHEN-MINUS character (-), the tool may insert a single U+0020 SPACE character at the end of such comments.
If the XML API restricts allowed characters in character data, attribute values, or comments, the tool may replace any U+000C FORM FEED (FF) character with a U+0020 SPACE character, and any other literal non-XML character with a U+FFFD REPLACEMENT CHARACTER.
If the tool has no way to convey out-of-band information, then the tool may drop the following information:
form
element ancestor (use of the form element
pointer in
the parser)
template
elements.
The mutations allowed by this section apply after the HTML
parser's rules have been applied. For example, a <a::> start tag
will be closed by a </a::> end tag, and never by a
</aU00003AU00003A>
end tag,
even if the user agent is using the rules above to
then generate an actual element in the DOM with the name aU00003AU00003A for
that start tag.
This section is non-normative.
This section examines some erroneous markup and discusses how the HTML parser handles these cases.
This section is non-normative.
The most-often discussed example of erroneous markup is as follows:
< p > 1< b > 2< i > 3</ b > 4</ i > 5</ p >
The parsing of this markup is straightforward up to the "3". At this point, the DOM looks like this:
Here, the stack of
open
elements has five elements on it: html,
body,
p, b, and i. The list of active
formatting elements just has two: b and i. The insertion
mode is "in
body".
Upon receiving the end tag token with the tag name "b", the "adoption
agency algorithm" is invoked. This is a simple case, in that the
formattingElement
is the b
element,
and there
is no furthest block.
Thus, the stack of
open
elements ends up with just three elements: html,
body,
and
p, while
the list of active formatting
elements
has just one: i.
The DOM
tree is unmodified at this point.
The next token is a character ("4"), triggers the reconstruction of
the active
formatting elements, in this case just
the i
element. A
new i
element is
thus created for
the "4"
Text
node. After the end tag token for the "i" is also received, and the "5"
Text
node is inserted, the DOM looks as follows:
This section is non-normative.
A case similar to the previous one is the following:
< b > 1< p > 2</ b > 3</ p >
Up to the "2" the parsing here is straightforward:
The interesting part is when the end tag token with the tag name "b" is parsed.
Before that token is seen, the stack of open elements has four
elements on
it:
html,
body,
b, and
p. The list of active
formatting elements just has the one: b. The insertion mode is
"in body".
Upon receiving the end tag token with the tag name "b", the "adoption
agency algorithm" is invoked, as in the previous example. However, in this case, there
is a furthest block, namely the p element.
Thus, this
time the adoption agency algorithm isn't skipped over.
The common ancestor is the body
element. A
conceptual
"bookmark" marks the position of the b in the list of active formatting
elements, but since that list has only one element in it, the bookmark won't have much
effect.
As the algorithm progresses, node ends up set to the formatting element
(b), and
last
node ends up set to the furthest
block (p).
The last node gets appended (moved) to the common ancestor, so that the DOM looks like:
A new b
element is
created,
and the children of the p
element are
moved to it:
Finally, the new b
element
is appended to the p
element, so that the
DOM looks like:
The b
element is
removed
from the list of active formatting
elements
and the stack of
open
elements, so that when the "3" is parsed, it is appended to the
p element:
This section is non-normative.
Error handling in tables is, for historical reasons, especially strange. For example, consider the following markup:
< table > < b > < tr >< td > aaa</ td ></ tr > bbb</ table > ccc
The highlighted b
element
start tag is not allowed directly inside a table like
that, and the parser handles this case by placing the element before the table. (This
is
called foster
parenting.)
This
can be seen by examining the DOM tree
as it stands just after the table
element's start
tag has been seen:
...and then immediately after the b element
start tag
has
been seen:
At this point, the stack of
open elements has on it the elements
html,
body,
table,
and
b (in
that order,
despite the resulting DOM tree); the list of active formatting
elements
just has the
b element
in it;
and the
insertion mode is "in
table".
The tr
start tag
causes
the b
element to
be
popped off the stack and
a tbody
start tag
to be implied; the tbody
and
tr
elements
are then handled in a rather straight-forward manner, taking the parser through the "in table
body"
and "in row"
insertion
modes, after
which the DOM looks as follows:
Here, the stack
of open
elements has on it the elements html,
body,
table,
tbody,
and tr;
the list of
active formatting elements still has the b element
in it;
and the
insertion mode is
"in row".
The td
element
start tag
token, after putting a td
element on the
tree, puts a marker
on
the list of active
formatting elements (it also switches to the "in
cell" insertion
mode).
The marker
means that
when the "aaa" character
tokens are seen, no b
element is created to hold the resulting Text
node:
The end tags are handled in a straight-forward manner; after handling them, the stack
of
open elements has on it the elements html,
body,
table,
and tbody;
the
list of active
formatting
elements
still has the b
element
in it (the marker
having been removed by the "td" end tag token); and the insertion mode is "in table
body".
Thus it is that the "bbb" character tokens are found. These trigger the "in
table
text" insertion mode to be used (with
the original
insertion mode set to "in table body").
The character tokens are collected, and when the next token (the table
element end
tag) is seen, they are processed as a group. Since they are not all spaces, they are handled as
per the "anything else" rules in the "in table"
insertion mode, which defer to the "in body"
insertion mode but with foster
parenting.
When the active
formatting
elements
are reconstructed, a b element
is
created and
foster parented, and
then the
"bbb"
Text
node is appended to it:
The stack
of open
elements has on it the elements html,
body,
table,
tbody,
and the new
b
(again, note
that this doesn't match the resulting tree!); the list of active
formatting
elements
has the new b
element in
it; and the insertion
mode
is still
"in table
body".
Had the character tokens been only ASCII
whitespace
instead of "bbb", then that
ASCII
whitespace would just be appended to the tbody
element.
Finally, the table
is
closed by
a "table" end tag. This pops all the nodes from
the stack of
open
elements up to and including the table
element, but
it
doesn't affect the list of active
formatting
elements,
so the "ccc" character tokens
after the table result in yet another b element
being
created,
this time after the
table:
This section is non-normative.
Consider the following markup, which for this example we will assume is the document with
URL
https://example.com/inner, being rendered as the content of
an iframe
in another document with the URL
https://example.com/outer:
< div id = a >
< script >
var div = document. getElementById( 'a' );
parent. document. body. appendChild( div);
</ script >
< script >
alert( document. URL);
</ script >
</ div >
< script >
alert( document. URL);
</ script >
Up to the first "script" end tag, before the script is parsed, the result is relatively straightforward:
After the script is parsed, though, the div
element and its child
script
element are gone:
They are, at this point, in the Document
of the
aforementioned outer
browsing
context. However, the stack of open
elements
still contains
the div
element.
Thus, when the second script
element is parsed, it is inserted into the outer
Document
object.
Those parsed into different Documents
than
the one the parser was created for do
not execute, so the first alert does not show.
Once the div
element's end tag is parsed, the div
element is popped
off the stack, and so the next script
element is in the inner
Document:
This script does execute, resulting in an alert that says "https://example.com/inner".
This section is non-normative.
Elaborating on the example in the previous section, consider the case where the second
script
element is an external script (i.e. one with a src
attribute). Since the element was not in the parser's
Document
when it was created, that external script is not even downloaded.
In a case where a script
element with a src
attribute is parsed normally into its parser's Document,
but while the external
script is being downloaded, the element is moved to another document, the script continues to
download, but does not execute.
In general, moving script
elements between Documents
is
considered a bad practice.
This section is non-normative.
The following markup shows how nested formatting elements (such as b) get
collected and continue to be applied even as the elements they are contained in are closed, but
that excessive duplicates are thrown away.
<!DOCTYPE html>
< p >< b class = x >< b class = x >< b >< b class = x >< b class = x >< b > X
< p > X
< p >< b >< b class = x >< b > X
< p ></ b ></ b ></ b ></ b ></ b ></ b > X
The resulting DOM tree is as follows:
html
html
Note how the second p
element in the markup has no explicit b
elements, but in the resulting DOM, up to three of each kind of formatting element (in this case
three b
elements with
the class attribute, and two unadorned b
elements)
get reconstructed before the element's "X".
Also note how this means that in the final paragraph only six b end
tags are
needed to completely clear the list of active formatting
elements,
even though nine
b start
tags
have been
seen up to this point.
For the purposes of the following algorithm, an element serializes as
void if
its
element type is one of the void
elements,
or is basefont,
bgsound, frame, keygen, or param.
The following steps form the HTML
fragment
serialization algorithm. The algorithm takes as input a DOM
Element,
Document, or DocumentFragment
referred to as
the node, a boolean serializableShadowRoots, and a
sequence<ShadowRoot> shadowRoots, and returns a string.
This algorithm serializes the children of the node being serialized, not the node itself.
If the node serializes as void, then return the empty string.
Let s be a string, and initialize it to the empty string.
If the node is a template
element, then let the node instead be the template
element's template
contents (a DocumentFragment
node).
If current node is a shadow host, then:
Let shadow be current node's shadow root.
If one of the following is true:
serializableShadowRoots is true and shadow's serializable is true; or
shadowRoots contains shadow,
then:
Append "<template shadowrootmode="".
If shadow's mode
is "open", then append "open".
Otherwise, append "closed".
Append """.
If shadow's delegates focus is set, then
append
" shadowrootdelegatesfocus=""".
If shadow's serializable is set,
then
append
" shadowrootserializable=""".
If shadow's clonable is set, then append
" shadowrootclonable=""".
Append ">".
Append the value of running the HTML fragment serialization algorithm with shadow, serializableShadowRoots, and shadowRoots (thus recursing into this algorithm for that element).
Append "</template>".
For each child node of the node, in tree order, run the following steps:
Let current node be the child node being processed.
Append the appropriate string from the following list to s:
Element
If current node is an element in the HTML namespace, the MathML namespace, or the SVG namespace, then let tagname be current node's local name. Otherwise, let tagname be current node's qualified name.
Append a U+003C LESS-THAN SIGN character (<), followed by tagname.
For HTML
elements created by the HTML parser or
createElement(),
tagname will be
lowercase.
If current node's is value
is not
null, and
the element does not have an is
attribute in
its attribute list, then append the string " is="",
followed by
current node's is value
escaped as
described below in attribute mode,
followed by a U+0022 QUOTATION MARK character (").
For each attribute that the element has, append a U+0020 SPACE character, the attribute's serialized name as described below, a U+003D EQUALS SIGN character (=), a U+0022 QUOTATION MARK character ("), the attribute's value, escaped as described below in attribute mode, and a second U+0022 QUOTATION MARK character (").
An attribute's serialized name for the purposes of the previous paragraph must be determined as follows:
The attribute's serialized name is the attribute's local name.
For attributes on HTML
elements set
by the
HTML
parser or by setAttribute(),
the
local name will be lowercase.
The attribute's serialized name is the string "xml:"
followed
by the attribute's local name.
xmlns
The attribute's serialized name is the string
"xmlns".
xmlns
The attribute's serialized name is the string
"xmlns:"
followed by the attribute's local name.
The attribute's serialized name is the string
"xlink:"
followed by the attribute's local name.
The attribute's serialized name is the attribute's qualified name.
While the exact order of attributes is implementation-defined, and may depend on factors such as the order that the attributes were given in the original markup, the sort order must be stable, such that consecutive invocations of this algorithm serialize an element's attributes in the same order.
Append a U+003E GREATER-THAN SIGN character (>).
If current node serializes as void, then continue on to the next child node at this point.
Append the value of running the HTML fragment serialization algorithm with current node, serializableShadowRoots, and shadowRoots (thus recursing into this algorithm for that node), followed by a U+003C LESS-THAN SIGN character (<), a U+002F SOLIDUS character (/), tagname again, and finally a U+003E GREATER-THAN SIGN character (>).
Text
node
If the parent of current node is a style,
script,
xmp,
iframe,
noembed,
noframes,
or
plaintext
element, or if the parent of current node is a noscript
element and scripting is
enabled for
the
node, then append the value of
current node's data literally.
Otherwise, append the value of current node's data, escaped as described below.
Comment
Append "<!--" (U+003C LESS-THAN SIGN, U+0021
EXCLAMATION MARK, U+002D HYPHEN-MINUS, U+002D HYPHEN-MINUS), followed by
the
value of
current node's data, followed by the
literal string "-->" (U+002D HYPHEN-MINUS, U+002D
HYPHEN-MINUS,
U+003E GREATER-THAN SIGN).
ProcessingInstruction
Append "<?" (U+003C LESS-THAN SIGN, U+003F
QUESTION MARK), followed by the value of current node's
target
IDL attribute, followed by a single U+0020 SPACE character, followed
by the value of current node's data,
followed by a single U+003E GREATER-THAN SIGN character (>).
DocumentType
Append "<!DOCTYPE" (U+003C LESS-THAN SIGN, U+0021
EXCLAMATION MARK, U+0044 LATIN CAPITAL LETTER D, U+004F LATIN CAPITAL
LETTER O,
U+0043
LATIN
CAPITAL LETTER C, U+0054 LATIN CAPITAL LETTER T, U+0059 LATIN CAPITAL
LETTER Y,
U+0050
LATIN
CAPITAL LETTER P, U+0045 LATIN CAPITAL LETTER E), followed by a space
(U+0020
SPACE),
followed by the value of current node's name, followed by
">"
(U+003E GREATER-THAN SIGN).
Return s.
It is possible that the output of this algorithm, if parsed with an HTML parser, will not return the original tree structure. Tree structures that do not roundtrip a serialize and reparse step can also be produced by the HTML parser itself, although such cases are typically non-conforming.
For instance, if a textarea
element to which a Comment
node has been appended is serialized and the output is then reparsed, the comment will end
up
being displayed in the text control. Similarly, if, as a result of DOM manipulation, an
element
contains a comment that contains "-->", then when
the result of serializing the element is parsed, the comment will be truncated at that point
and
the rest of the comment will be interpreted as markup. More examples would be making a
script
element contain a Text
node with the text string "</script>", or having a p element
that
contains a
ul
element (as
the
ul
element's
start
tag would imply the end tag for the p).
This can enable cross-site scripting attacks. An example of this would be a page that lets
the
user enter some font family names that are then inserted into a CSS style
block via
the DOM and which then uses the innerHTML
IDL attribute to get
the HTML serialization of that style
element:
if the user enters
"</style><script>attack</script>" as a font family name, innerHTML
will return markup that, if parsed in a different context,
would contain a script
node,
even though no script
node
existed in the
original DOM.
For example, consider the following markup:
< form id = "outer" >< div ></ form >< form id = "inner" >< input >
This will be parsed into:
The input
element will be associated with the inner form
element.
Now, if this tree structure is serialized and reparsed, the <form
id="inner"> start tag will be ignored, and so the input
element
will be
associated with the outer form
element
instead.
< html >< head ></ head >< body >< form id = "outer" >< div > < form id = "inner" > < input ></ form ></ div ></ form ></ body ></ html >
As another example, consider the following markup:
< a >< table >< a >
This will be parsed into:
That is, the a
elements
are nested, because the second a
element is
foster parented.
After a
serialize-reparse roundtrip, the
a
elements and
the
table
element
would all be siblings, because the
second <a> start tag implicitly closes the first a
element.
< html >< head ></ head >< body >< a > < a > </ a >< table ></ table ></ a ></ body ></ html >
For historical reasons, this algorithm does not round-trip an initial U+000A LINE FEED (LF)
character in pre,
textarea,
or
listing elements, even
though (in the first two cases) the markup being round-tripped can be conforming. The HTML
parser will drop such a character during parsing, but this algorithm does not
serialize an extra U+000A LINE FEED (LF) character.
For example, consider the following markup:
< pre >
Hello.</ pre >
When this document is first parsed, the pre
element's child
text
content starts with a single newline character. After a serialize-reparse roundtrip,
the
pre
element's child
text content is simply "Hello.".
Because of the special role of the is attribute in
signaling the
creation
of customized
built-in elements, in that it provides a mechanism for parsed
HTML to set the element's is
value, we special-case its handling during serialization. This ensures that an element's
is value is preserved
through serialize-parse roundtrips.
When creating a customized built-in
element via
the
parser, a developer uses the is
attribute directly; in such cases serialize-parse roundtrips work fine.
< script >
window. SuperP = class extends HTMLParagraphElement {};
customElements. define( "super-p" , SuperP, { extends : "p" });
</ script >
< div id = "container" >< p is = "super-p" > Superb!</ p ></ div >
< script >
console. log( container. innerHTML); // <p is="super-p">
container. innerHTML = container. innerHTML;
console. log( container. innerHTML); // <p is="super-p">
console. assert( container. firstChild instanceof SuperP);
</ script >
But when creating a customized built-in element via its constructor or via createElement(),
the is
attribute is not added. Instead, the is value (which is what the
custom
elements
machinery uses) is set
without intermediating through an attribute.
< script >
container. innerHTML = "" ;
const p = document. createElement( "p" , { is: "super-p" });
container. appendChild( p);
// The is attribute is not present in the DOM:
console. assert( ! p. hasAttribute( "is" ));
// But the element is still a super-p:
console. assert( p instanceof SuperP);
</ script >
To ensure that serialize-parse roundtrips still work, the serialization process explicitly
writes out the element's is
value as an is
attribute:
< script >
console. log( container. innerHTML); // <p is="super-p">
container. innerHTML = container. innerHTML;
console. log( container. innerHTML); // <p is="super-p">
console. assert( container. firstChild instanceof SuperP);
</ script >
Escaping a string (for the purposes of the algorithm above) consists of running the following steps:
Replace any occurrence of the "&" character by the string
"&".
Replace any occurrences of the U+00A0 NO-BREAK SPACE character by the string
" ".
If the algorithm was invoked in the attribute mode, replace any occurrences of the
""" character by the string """.
If the algorithm was not invoked in the attribute mode, replace any
occurrences of the "<" character by the string "<",
and any
occurrences of the ">" character by
the string ">".
The following steps form the HTML fragment parsing
algorithm. The
algorithm
takes as input an Element
node, referred to as the context element,
which
gives the
context for
the parser, input, a string to parse, and an optional boolean
allowDeclarativeShadowRoots (default false). It returns a list of zero or more
nodes.
Parts marked fragment case in algorithms in the parser section are parts that only occur if the parser was created for the purposes of this algorithm. The algorithms have been annotated with such markings for informational purposes only; such markings have no normative weight. If it is possible for a condition described as a fragment case to occur even when the parser wasn't created for the purposes of handling this algorithm, then that is an error in the specification.
Create a new Document node,
and
mark it as being an HTML
document.
If the
node
document of the context element is in
quirks
mode, then let the Document be in quirks
mode.
Otherwise, if the
node
document of the context element is in
limited-quirks mode, then let the Document be in limited-quirks
mode. Otherwise, leave the Document in no-quirks mode.
If allowDeclarativeShadowRoots is true, then set the Document's
allow declarative
shadow
roots to true.
Create a new HTML parser,
and
associate it
with the just created
Document node.
Set the state of the HTML parser's tokenization stage as follows, switching on the context element:
title
textarea
style
xmp
iframe
noembed
noframes
script
noscript
plaintext
For performance reasons, an implementation that does not report errors and that uses the actual state machine described in this specification directly could use the PLAINTEXT state instead of the RAWTEXT and script data states where those are mentioned in the list above. Except for rules regarding parse errors, they are equivalent, since there is no appropriate end tag token in the fragment case, yet they involve far fewer state transitions.
Let root be a new html
element
with no
attributes.
Append the element root to the Document node
created
above.
Set up the parser's stack of open elements so that it contains just the single element root.
If the context element is a
template
element, push "in
template" onto the stack of template
insertion
modes so
that it is the new
current template insertion
mode.
Create a start tag token whose name is the local name of context and whose attributes are the attributes of context.
Let this start tag token be the start tag token of the context node, e.g. for the purposes of determining if it is an HTML integration point.
Reset the parser's insertion mode appropriately.
The parser will reference the context element as part of that algorithm.
Set the parser's form element pointer
to the
nearest
node to the
context element that is a form
element (going straight up the ancestor chain, and including the element itself, if it
is a
form
element),
if any. (If there is no such form
element, the
form
element
pointer keeps its initial value, null.)
Place the input into the input stream for the HTML parser just created. The encoding confidence is irrelevant.
Start the parser and let it run until it has consumed all the characters just inserted into the input stream.
Return the child nodes of root, in tree order.
This table lists the character reference names that are supported by HTML, and the code points to which they refer. It is referenced by the previous sections.
It is intentional, for legacy compatibility, that many code points have multiple character reference names. For example, some appear both with and without the trailing semicolon, or with different capitalizations.
| Name | Character(s) | Glyph |
|---|---|---|
Aacute;
| U+000C1 | Á |
Aacute
| U+000C1 | Á |
aacute;
| U+000E1 | á |
aacute
| U+000E1 | á |
Abreve;
| U+00102 | Ă |
abreve;
| U+00103 | ă |
ac;
| U+0223E | ∾ |
acd;
| U+0223F | ∿ |
acE;
| U+0223E U+00333 | ∾̳ |
Acirc;
| U+000C2 | Â |
Acirc
| U+000C2 | Â |
acirc;
| U+000E2 | â |
acirc
| U+000E2 | â |
acute;
| U+000B4 | ´ |
acute
| U+000B4 | ´ |
Acy;
| U+00410 | А |
acy;
| U+00430 | а |
AElig;
| U+000C6 | Æ |
AElig
| U+000C6 | Æ |
aelig;
| U+000E6 | æ |
aelig
| U+000E6 | æ |
af;
| U+02061 | |
Afr;
| U+1D504 | 𝔄 |
afr;
| U+1D51E | 𝔞 |
Agrave;
| U+000C0 | À |
Agrave
| U+000C0 | À |
agrave;
| U+000E0 | à |
agrave
| U+000E0 | à |
alefsym;
| U+02135 | ℵ |
aleph;
| U+02135 | ℵ |
Alpha;
| U+00391 | Α |
alpha;
| U+003B1 | α |
Amacr;
| U+00100 | Ā |
amacr;
| U+00101 | ā |
amalg;
| U+02A3F | ⨿ |
AMP;
| U+00026 | & |
AMP
| U+00026 | & |
amp;
| U+00026 | & |
amp
| U+00026 | & |
And;
| U+02A53 | ⩓ |
and;
| U+02227 | ∧ |
andand;
| U+02A55 | ⩕ |
andd;
| U+02A5C | ⩜ |
andslope;
| U+02A58 | ⩘ |
andv;
| U+02A5A | ⩚ |
ang;
| U+02220 | ∠ |
ange;
| U+029A4 | ⦤ |
angle;
| U+02220 | ∠ |
angmsd;
| U+02221 | ∡ |
angmsdaa;
| U+029A8 | ⦨ |
angmsdab;
| U+029A9 | ⦩ |
angmsdac;
| U+029AA | ⦪ |
angmsdad;
| U+029AB | ⦫ |
angmsdae;
| U+029AC | ⦬ |
angmsdaf;
| U+029AD | ⦭ |
angmsdag;
| U+029AE | ⦮ |
angmsdah;
| U+029AF | ⦯ |
angrt;
| U+0221F | ∟ |
angrtvb;
| U+022BE | ⊾ |
angrtvbd;
| U+0299D | ⦝ |
angsph;
| U+02222 | ∢ |
angst;
| U+000C5 | Å |
angzarr;
| U+0237C | ⍼ |
Aogon;
| U+00104 | Ą |
aogon;
| U+00105 | ą |
Aopf;
| U+1D538 | 𝔸 |
aopf;
| U+1D552 | 𝕒 |
ap;
| U+02248 | ≈ |
apacir;
| U+02A6F | ⩯ |
apE;
| U+02A70 | ⩰ |
ape;
| U+0224A | ≊ |
apid;
| U+0224B | ≋ |
apos;
| U+00027 | ' |
ApplyFunction;
| U+02061 | |
approx;
| U+02248 | ≈ |
approxeq;
| U+0224A | ≊ |
Aring;
| U+000C5 | Å |
Aring
| U+000C5 | Å |
aring;
| U+000E5 | å |
aring
| U+000E5 | å |
Ascr;
| U+1D49C | 𝒜 |
ascr;
| U+1D4B6 | 𝒶 |
Assign;
| U+02254 | ≔ |
ast;
| U+0002A | * |
asymp;
| U+02248 | ≈ |
asympeq;
| U+0224D | ≍ |
Atilde;
| U+000C3 | Ã |
Atilde
| U+000C3 | Ã |
atilde;
| U+000E3 | ã |
atilde
| U+000E3 | ã |
Auml;
| U+000C4 | Ä |
Auml
| U+000C4 | Ä |
auml;
| U+000E4 | ä |
auml
| U+000E4 | ä |
awconint;
| U+02233 | ∳ |
awint;
| U+02A11 | ⨑ |
backcong;
| U+0224C | ≌ |
backepsilon;
| U+003F6 | ϶ |
backprime;
| U+02035 | ‵ |
backsim;
| U+0223D | ∽ |
backsimeq;
| U+022CD | ⋍ |
Backslash;
| U+02216 | ∖ |
Barv;
| U+02AE7 | ⫧ |
barvee;
| U+022BD | ⊽ |
Barwed;
| U+02306 | ⌆ |
barwed;
| U+02305 | ⌅ |
barwedge;
| U+02305 | ⌅ |
bbrk;
| U+023B5 | ⎵ |
bbrktbrk;
| U+023B6 | ⎶ |
bcong;
| U+0224C | ≌ |
Bcy;
| U+00411 | Б |
bcy;
| U+00431 | б |
bdquo;
| U+0201E | „ |
becaus;
| U+02235 | ∵ |
Because;
| U+02235 | ∵ |
because;
| U+02235 | ∵ |
bemptyv;
| U+029B0 | ⦰ |
bepsi;
| U+003F6 | ϶ |
bernou;
| U+0212C | ℬ |
Bernoullis;
| U+0212C | ℬ |
Beta;
| U+00392 | Β |
beta;
| U+003B2 | β |
beth;
| U+02136 | ℶ |
between;
| U+0226C | ≬ |
Bfr;
| U+1D505 | 𝔅 |
bfr;
| U+1D51F | 𝔟 |
bigcap;
| U+022C2 | ⋂ |
bigcirc;
| U+025EF | ◯ |
bigcup;
| U+022C3 | ⋃ |
bigodot;
| U+02A00 | ⨀ |
bigoplus;
| U+02A01 | ⨁ |
bigotimes;
| U+02A02 | ⨂ |
bigsqcup;
| U+02A06 | ⨆ |
bigstar;
| U+02605 | ★ |
bigtriangledown;
| U+025BD | ▽ |
bigtriangleup;
| U+025B3 | △ |
biguplus;
| U+02A04 | ⨄ |
bigvee;
| U+022C1 | ⋁ |
bigwedge;
| U+022C0 | ⋀ |
bkarow;
| U+0290D | ⤍ |
blacklozenge;
| U+029EB | ⧫ |
blacksquare;
| U+025AA | ▪ |
blacktriangle;
| U+025B4 | ▴ |
blacktriangledown;
| U+025BE | ▾ |
blacktriangleleft;
| U+025C2 | ◂ |
blacktriangleright;
| U+025B8 | ▸ |
blank;
| U+02423 | ␣ |
blk12;
| U+02592 | ▒ |
blk14;
| U+02591 | ░ |
blk34;
| U+02593 | ▓ |
block;
| U+02588 | █ |
bne;
| U+0003D U+020E5 | =⃥ |
bnequiv;
| U+02261 U+020E5 | ≡⃥ |
bNot;
| U+02AED | ⫭ |
bnot;
| U+02310 | ⌐ |
Bopf;
| U+1D539 | 𝔹 |
bopf;
| U+1D553 | 𝕓 |
bot;
| U+022A5 | ⊥ |
bottom;
| U+022A5 | ⊥ |
bowtie;
| U+022C8 | ⋈ |
boxbox;
| U+029C9 | ⧉ |
boxDL;
| U+02557 | ╗ |
boxDl;
| U+02556 | ╖ |
boxdL;
| U+02555 | ╕ |
boxdl;
| U+02510 | ┐ |
boxDR;
| U+02554 | ╔ |
boxDr;
| U+02553 | ╓ |
boxdR;
| U+02552 | ╒ |
boxdr;
| U+0250C | ┌ |
boxH;
| U+02550 | ═ |
boxh;
| U+02500 | ─ |
boxHD;
| U+02566 | ╦ |
boxHd;
| U+02564 | ╤ |
boxhD;
| U+02565 | ╥ |
boxhd;
| U+0252C | ┬ |
boxHU;
| U+02569 | ╩ |
boxHu;
| U+02567 | ╧ |
boxhU;
| U+02568 | ╨ |
boxhu;
| U+02534 | ┴ |
boxminus;
| U+0229F | ⊟ |
boxplus;
| U+0229E | ⊞ |
boxtimes;
| U+022A0 | ⊠ |
boxUL;
| U+0255D | ╝ |
boxUl;
| U+0255C | ╜ |
boxuL;
| U+0255B | ╛ |
boxul;
| U+02518 | ┘ |
boxUR;
| U+0255A | ╚ |
boxUr;
| U+02559 | ╙ |
boxuR;
| U+02558 | ╘ |
boxur;
| U+02514 | └ |
boxV;
| U+02551 | ║ |
boxv;
| U+02502 | │ |
boxVH;
| U+0256C | ╬ |
boxVh;
| U+0256B | ╫ |
boxvH;
| U+0256A | ╪ |
boxvh;
| U+0253C | ┼ |
boxVL;
| U+02563 | ╣ |
boxVl;
| U+02562 | ╢ |
boxvL;
| U+02561 | ╡ |
boxvl;
| U+02524 | ┤ |
boxVR;
| U+02560 | ╠ |
boxVr;
| U+0255F | ╟ |
boxvR;
| U+0255E | ╞ |
boxvr;
| U+0251C | ├ |
bprime;
| U+02035 | ‵ |
Breve;
| U+002D8 | ˘ |
breve;
| U+002D8 | ˘ |
brvbar;
| U+000A6 | ¦ |
brvbar
| U+000A6 | ¦ |
Bscr;
| U+0212C | ℬ |
bscr;
| U+1D4B7 | 𝒷 |
bsemi;
| U+0204F | ⁏ |
bsim;
| U+0223D | ∽ |
bsime;
| U+022CD | ⋍ |
bsol;
| U+0005C | \ |
bsolb;
| U+029C5 | ⧅ |
bsolhsub;
| U+027C8 | ⟈ |
bull;
| U+02022 | • |
bullet;
| U+02022 | • |
bump;
| U+0224E | ≎ |
bumpE;
| U+02AAE | ⪮ |
bumpe;
| U+0224F | ≏ |
Bumpeq;
| U+0224E | ≎ |
bumpeq;
| U+0224F | ≏ |
Cacute;
| U+00106 | Ć |
cacute;
| U+00107 | ć |
Cap;
| U+022D2 | ⋒ |
cap;
| U+02229 | ∩ |
capand;
| U+02A44 | ⩄ |
capbrcup;
| U+02A49 | ⩉ |
capcap;
| U+02A4B | ⩋ |
capcup;
| U+02A47 | ⩇ |
capdot;
| U+02A40 | ⩀ |
CapitalDifferentialD;
| U+02145 | ⅅ |
caps;
| U+02229 U+0FE00 | ∩︀ |
caret;
| U+02041 | ⁁ |
caron;
| U+002C7 | ˇ |
Cayleys;
| U+0212D | ℭ |
ccaps;
| U+02A4D | ⩍ |
Ccaron;
| U+0010C | Č |
ccaron;
| U+0010D | č |
Ccedil;
| U+000C7 | Ç |
Ccedil
| U+000C7 | Ç |
ccedil;
| U+000E7 | ç |
ccedil
| U+000E7 | ç |
Ccirc;
| U+00108 | Ĉ |
ccirc;
| U+00109 | ĉ |
Cconint;
| U+02230 | ∰ |
ccups;
| U+02A4C | ⩌ |
ccupssm;
| U+02A50 | ⩐ |
Cdot;
| U+0010A | Ċ |
cdot;
| U+0010B | ċ |
cedil;
| U+000B8 | ¸ |
cedil
| U+000B8 | ¸ |
Cedilla;
| U+000B8 | ¸ |
cemptyv;
| U+029B2 | ⦲ |
cent;
| U+000A2 | ¢ |
cent
| U+000A2 | ¢ |
CenterDot;
| U+000B7 | · |
centerdot;
| U+000B7 | · |
Cfr;
| U+0212D | ℭ |
cfr;
| U+1D520 | 𝔠 |
CHcy;
| U+00427 | Ч |
chcy;
| U+00447 | ч |
check;
| U+02713 | ✓ |
checkmark;
| U+02713 | ✓ |
Chi;
| U+003A7 | Χ |
chi;
| U+003C7 | χ |
cir;
| U+025CB | ○ |
circ;
| U+002C6 | ˆ |
circeq;
| U+02257 | ≗ |
circlearrowleft;
| U+021BA | ↺ |
circlearrowright;
| U+021BB | ↻ |
circledast;
| U+0229B | ⊛ |
circledcirc;
| U+0229A | ⊚ |
circleddash;
| U+0229D | ⊝ |
CircleDot;
| U+02299 | ⊙ |
circledR;
| U+000AE | ® |
circledS;
| U+024C8 | Ⓢ |
CircleMinus;
| U+02296 | ⊖ |
CirclePlus;
| U+02295 | ⊕ |
CircleTimes;
| U+02297 | ⊗ |
cirE;
| U+029C3 | ⧃ |
cire;
| U+02257 | ≗ |
cirfnint;
| U+02A10 | ⨐ |
cirmid;
| U+02AEF | ⫯ |
cirscir;
| U+029C2 | ⧂ |
ClockwiseContourIntegral;
| U+02232 | ∲ |
CloseCurlyDoubleQuote;
| U+0201D | ” |
CloseCurlyQuote;
| U+02019 | ’ |
clubs;
| U+02663 | ♣ |
clubsuit;
| U+02663 | ♣ |
Colon;
| U+02237 | ∷ |
colon;
| U+0003A | : |
Colone;
| U+02A74 | ⩴ |
colone;
| U+02254 | ≔ |
coloneq;
| U+02254 | ≔ |
comma;
| U+0002C | , |
commat;
| U+00040 | @ |
comp;
| U+02201 | ∁ |
compfn;
| U+02218 | ∘ |
complement;
| U+02201 | ∁ |
complexes;
| U+02102 | ℂ |
cong;
| U+02245 | ≅ |
congdot;
| U+02A6D | ⩭ |
Congruent;
| U+02261 | ≡ |
Conint;
| U+0222F | ∯ |
conint;
| U+0222E | ∮ |
ContourIntegral;
| U+0222E | ∮ |
Copf;
| U+02102 | ℂ |
copf;
| U+1D554 | 𝕔 |
coprod;
| U+02210 | ∐ |
Coproduct;
| U+02210 | ∐ |
COPY;
| U+000A9 | © |
COPY
| U+000A9 | © |
copy;
| U+000A9 | © |
copy
| U+000A9 | © |
copysr;
| U+02117 | ℗ |
CounterClockwiseContourIntegral;
| U+02233 | ∳ |
crarr;
| U+021B5 | ↵ |
Cross;
| U+02A2F | ⨯ |
cross;
| U+02717 | ✗ |
Cscr;
| U+1D49E | 𝒞 |
cscr;
| U+1D4B8 | 𝒸 |
csub;
| U+02ACF | ⫏ |
csube;
| U+02AD1 | ⫑ |
csup;
| U+02AD0 | ⫐ |
csupe;
| U+02AD2 | ⫒ |
ctdot;
| U+022EF | ⋯ |
cudarrl;
| U+02938 | ⤸ |
cudarrr;
| U+02935 | ⤵ |
cuepr;
| U+022DE | ⋞ |
cuesc;
| U+022DF | ⋟ |
cularr;
| U+021B6 | ↶ |
cularrp;
| U+0293D | ⤽ |
Cup;
| U+022D3 | ⋓ |
cup;
| U+0222A | ∪ |
cupbrcap;
| U+02A48 | ⩈ |
CupCap;
| U+0224D | ≍ |
cupcap;
| U+02A46 | ⩆ |
cupcup;
| U+02A4A | ⩊ |
cupdot;
| U+0228D | ⊍ |
cupor;
| U+02A45 | ⩅ |
cups;
| U+0222A U+0FE00 | ∪︀ |
curarr;
| U+021B7 | ↷ |
curarrm;
| U+0293C | ⤼ |
curlyeqprec;
| U+022DE | ⋞ |
curlyeqsucc;
| U+022DF | ⋟ |
curlyvee;
| U+022CE | ⋎ |
curlywedge;
| U+022CF | ⋏ |
curren;
| U+000A4 | ¤ |
curren
| U+000A4 | ¤ |
curvearrowleft;
| U+021B6 | ↶ |
curvearrowright;
| U+021B7 | ↷ |
cuvee;
| U+022CE | ⋎ |
cuwed;
| U+022CF | ⋏ |
cwconint;
| U+02232 | ∲ |
cwint;
| U+02231 | ∱ |
cylcty;
| U+0232D | ⌭ |
Dagger;
| U+02021 | ‡ |
dagger;
| U+02020 | † |
daleth;
| U+02138 | ℸ |
Darr;
| U+021A1 | ↡ |
dArr;
| U+021D3 | ⇓ |
darr;
| U+02193 | ↓ |
dash;
| U+02010 | ‐ |
Dashv;
| U+02AE4 | ⫤ |
dashv;
| U+022A3 | ⊣ |
dbkarow;
| U+0290F | ⤏ |
dblac;
| U+002DD | ˝ |
Dcaron;
| U+0010E | Ď |
dcaron;
| U+0010F | ď |
Dcy;
| U+00414 | Д |
dcy;
| U+00434 | д |
DD;
| U+02145 | ⅅ |
dd;
| U+02146 | ⅆ |
ddagger;
| U+02021 | ‡ |
ddarr;
| U+021CA | ⇊ |
DDotrahd;
| U+02911 | ⤑ |
ddotseq;
| U+02A77 | ⩷ |
deg;
| U+000B0 | ° |
deg
| U+000B0 | ° |
Del;
| U+02207 | ∇ |
Delta;
| U+00394 | Δ |
delta;
| U+003B4 | δ |
demptyv;
| U+029B1 | ⦱ |
dfisht;
| U+0297F | ⥿ |
Dfr;
| U+1D507 | 𝔇 |
dfr;
| U+1D521 | 𝔡 |
dHar;
| U+02965 | ⥥ |
dharl;
| U+021C3 | ⇃ |
dharr;
| U+021C2 | ⇂ |
DiacriticalAcute;
| U+000B4 | ´ |
DiacriticalDot;
| U+002D9 | ˙ |
DiacriticalDoubleAcute;
| U+002DD | ˝ |
DiacriticalGrave;
| U+00060 | ` |
DiacriticalTilde;
| U+002DC | ˜ |
diam;
| U+022C4 | ⋄ |
Diamond;
| U+022C4 | ⋄ |
diamond;
| U+022C4 | ⋄ |
diamondsuit;
| U+02666 | ♦ |
diams;
| U+02666 | ♦ |
die;
| U+000A8 | ¨ |
DifferentialD;
| U+02146 | ⅆ |
digamma;
| U+003DD | ϝ |
disin;
| U+022F2 | ⋲ |
div;
| U+000F7 | ÷ |
divide;
| U+000F7 | ÷ |
divide
| U+000F7 | ÷ |
divideontimes;
| U+022C7 | ⋇ |
divonx;
| U+022C7 | ⋇ |
DJcy;
| U+00402 | Ђ |
djcy;
| U+00452 | ђ |
dlcorn;
| U+0231E | ⌞ |
dlcrop;
| U+0230D | ⌍ |
dollar;
| U+00024 | $ |
Dopf;
| U+1D53B | 𝔻 |
dopf;
| U+1D555 | 𝕕 |
Dot;
| U+000A8 | ¨ |
dot;
| U+002D9 | ˙ |
DotDot;
| U+020DC | ◌⃜ |
doteq;
| U+02250 | ≐ |
doteqdot;
| U+02251 | ≑ |
DotEqual;
| U+02250 | ≐ |
dotminus;
| U+02238 | ∸ |
dotplus;
| U+02214 | ∔ |
dotsquare;
| U+022A1 | ⊡ |
doublebarwedge;
| U+02306 | ⌆ |
DoubleContourIntegral;
| U+0222F | ∯ |
DoubleDot;
| U+000A8 | ¨ |
DoubleDownArrow;
| U+021D3 | ⇓ |
DoubleLeftArrow;
| U+021D0 | ⇐ |
DoubleLeftRightArrow;
| U+021D4 | ⇔ |
DoubleLeftTee;
| U+02AE4 | ⫤ |
DoubleLongLeftArrow;
| U+027F8 | ⟸ |
DoubleLongLeftRightArrow;
| U+027FA | ⟺ |
DoubleLongRightArrow;
| U+027F9 | ⟹ |
DoubleRightArrow;
| U+021D2 | ⇒ |
DoubleRightTee;
| U+022A8 | ⊨ |
DoubleUpArrow;
| U+021D1 | ⇑ |
DoubleUpDownArrow;
| U+021D5 | ⇕ |
DoubleVerticalBar;
| U+02225 | ∥ |
DownArrow;
| U+02193 | ↓ |
Downarrow;
| U+021D3 | ⇓ |
downarrow;
| U+02193 | ↓ |
DownArrowBar;
| U+02913 | ⤓ |
DownArrowUpArrow;
| U+021F5 | ⇵ |
DownBreve;
| U+00311 | ◌̑ |
downdownarrows;
| U+021CA | ⇊ |
downharpoonleft;
| U+021C3 | ⇃ |
downharpoonright;
| U+021C2 | ⇂ |
DownLeftRightVector;
| U+02950 | ⥐ |
DownLeftTeeVector;
| U+0295E | ⥞ |
DownLeftVector;
| U+021BD | ↽ |
DownLeftVectorBar;
| U+02956 | ⥖ |
DownRightTeeVector;
| U+0295F | ⥟ |
DownRightVector;
| U+021C1 | ⇁ |
DownRightVectorBar;
| U+02957 | ⥗ |
DownTee;
| U+022A4 | ⊤ |
DownTeeArrow;
| U+021A7 | ↧ |
drbkarow;
| U+02910 | ⤐ |
drcorn;
| U+0231F | ⌟ |
drcrop;
| U+0230C | ⌌ |
Dscr;
| U+1D49F | 𝒟 |
dscr;
| U+1D4B9 | 𝒹 |
DScy;
| U+00405 | Ѕ |
dscy;
| U+00455 | ѕ |
dsol;
| U+029F6 | ⧶ |
Dstrok;
| U+00110 | Đ |
dstrok;
| U+00111 | đ |
dtdot;
| U+022F1 | ⋱ |
dtri;
| U+025BF | ▿ |
dtrif;
| U+025BE | ▾ |
duarr;
| U+021F5 | ⇵ |
duhar;
| U+0296F | ⥯ |
dwangle;
| U+029A6 | ⦦ |
DZcy;
| U+0040F | Џ |
dzcy;
| U+0045F | џ |
dzigrarr;
| U+027FF | ⟿ |
Eacute;
| U+000C9 | É |
Eacute
| U+000C9 | É |
eacute;
| U+000E9 | é |
eacute
| U+000E9 | é |
easter;
| U+02A6E | ⩮ |
Ecaron;
| U+0011A | Ě |
ecaron;
| U+0011B | ě |
ecir;
| U+02256 | ≖ |
Ecirc;
| U+000CA | Ê |
Ecirc
| U+000CA | Ê |
ecirc;
| U+000EA | ê |
ecirc
| U+000EA | ê |
ecolon;
| U+02255 | ≕ |
Ecy;
| U+0042D | Э |
ecy;
| U+0044D | э |
eDDot;
| U+02A77 | ⩷ |
Edot;
| U+00116 | Ė |
eDot;
| U+02251 | ≑ |
edot;
| U+00117 | ė |
ee;
| U+02147 | ⅇ |
efDot;
| U+02252 | ≒ |
Efr;
| U+1D508 | 𝔈 |
efr;
| U+1D522 | 𝔢 |
eg;
| U+02A9A | ⪚ |
Egrave;
| U+000C8 | È |
Egrave
| U+000C8 | È |
egrave;
| U+000E8 | è |
egrave
| U+000E8 | è |
egs;
| U+02A96 | ⪖ |
egsdot;
| U+02A98 | ⪘ |
el;
| U+02A99 | ⪙ |
Element;
| U+02208 | ∈ |
elinters;
| U+023E7 | ⏧ |
ell;
| U+02113 | ℓ |
els;
| U+02A95 | ⪕ |
elsdot;
| U+02A97 | ⪗ |
Emacr;
| U+00112 | Ē |
emacr;
| U+00113 | ē |
empty;
| U+02205 | ∅ |
emptyset;
| U+02205 | ∅ |
EmptySmallSquare;
| U+025FB | ◻ |
emptyv;
| U+02205 | ∅ |
EmptyVerySmallSquare;
| U+025AB | ▫ |
emsp;
| U+02003 | |
emsp13;
| U+02004 | |
emsp14;
| U+02005 | |
ENG;
| U+0014A | Ŋ |
eng;
| U+0014B | ŋ |
ensp;
| U+02002 | |
Eogon;
| U+00118 | Ę |
eogon;
| U+00119 | ę |
Eopf;
| U+1D53C | 𝔼 |
eopf;
| U+1D556 | 𝕖 |
epar;
| U+022D5 | ⋕ |
eparsl;
| U+029E3 | ⧣ |
eplus;
| U+02A71 | ⩱ |
epsi;
| U+003B5 | ε |
Epsilon;
| U+00395 | Ε |
epsilon;
| U+003B5 | ε |
epsiv;
| U+003F5 | ϵ |
eqcirc;
| U+02256 | ≖ |
eqcolon;
| U+02255 | ≕ |
eqsim;
| U+02242 | ≂ |
eqslantgtr;
| U+02A96 | ⪖ |
eqslantless;
| U+02A95 | ⪕ |
Equal;
| U+02A75 | ⩵ |
equals;
| U+0003D | = |
EqualTilde;
| U+02242 | ≂ |
equest;
| U+0225F | ≟ |
Equilibrium;
| U+021CC | ⇌ |
equiv;
| U+02261 | ≡ |
equivDD;
| U+02A78 | ⩸ |
eqvparsl;
| U+029E5 | ⧥ |
erarr;
| U+02971 | ⥱ |
erDot;
| U+02253 | ≓ |
Escr;
| U+02130 | ℰ |
escr;
| U+0212F | ℯ |
esdot;
| U+02250 | ≐ |
Esim;
| U+02A73 | ⩳ |
esim;
| U+02242 | ≂ |
Eta;
| U+00397 | Η |
eta;
| U+003B7 | η |
ETH;
| U+000D0 | Ð |
ETH
| U+000D0 | Ð |
eth;
| U+000F0 | ð |
eth
| U+000F0 | ð |
Euml;
| U+000CB | Ë |
Euml
| U+000CB | Ë |
euml;
| U+000EB | ë |
euml
| U+000EB | ë |
euro;
| U+020AC | € |
excl;
| U+00021 | ! |
exist;
| U+02203 | ∃ |
Exists;
| U+02203 | ∃ |
expectation;
| U+02130 | ℰ |
ExponentialE;
| U+02147 | ⅇ |
exponentiale;
| U+02147 | ⅇ |
fallingdotseq;
| U+02252 | ≒ |
Fcy;
| U+00424 | Ф |
fcy;
| U+00444 | ф |
female;
| U+02640 | ♀ |
ffilig;
| U+0FB03 | ffi |
fflig;
| U+0FB00 | ff |
ffllig;
| U+0FB04 | ffl |
Ffr;
| U+1D509 | 𝔉 |
ffr;
| U+1D523 | 𝔣 |
filig;
| U+0FB01 | fi |
FilledSmallSquare;
| U+025FC | ◼ |
FilledVerySmallSquare;
| U+025AA | ▪ |
fjlig;
| U+00066 U+0006A | fj |
flat;
| U+0266D | ♭ |
fllig;
| U+0FB02 | fl |
fltns;
| U+025B1 | ▱ |
fnof;
| U+00192 | ƒ |
Fopf;
| U+1D53D | 𝔽 |
fopf;
| U+1D557 | 𝕗 |
ForAll;
| U+02200 | ∀ |
forall;
| U+02200 | ∀ |
fork;
| U+022D4 | ⋔ |
forkv;
| U+02AD9 | ⫙ |
Fouriertrf;
| U+02131 | ℱ |
fpartint;
| U+02A0D | ⨍ |
frac12;
| U+000BD | ½ |
frac12
| U+000BD | ½ |
frac13;
| U+02153 | ⅓ |
frac14;
| U+000BC | ¼ |
frac14
| U+000BC | ¼ |
frac15;
| U+02155 | ⅕ |
frac16;
| U+02159 | ⅙ |
frac18;
| U+0215B | ⅛ |
frac23;
| U+02154 | ⅔ |
frac25;
| U+02156 | ⅖ |
frac34;
| U+000BE | ¾ |
frac34
| U+000BE | ¾ |
frac35;
| U+02157 | ⅗ |
frac38;
| U+0215C | ⅜ |
frac45;
| U+02158 | ⅘ |
frac56;
| U+0215A | ⅚ |
frac58;
| U+0215D | ⅝ |
frac78;
| U+0215E | ⅞ |
frasl;
| U+02044 | ⁄ |
frown;
| U+02322 | ⌢ |
Fscr;
| U+02131 | ℱ |
fscr;
| U+1D4BB | 𝒻 |
gacute;
| U+001F5 | ǵ |
Gamma;
| U+00393 | Γ |
gamma;
| U+003B3 | γ |
Gammad;
| U+003DC | Ϝ |
gammad;
| U+003DD | ϝ |
gap;
| U+02A86 | ⪆ |
Gbreve;
| U+0011E | Ğ |
gbreve;
| U+0011F | ğ |
Gcedil;
| U+00122 | Ģ |
Gcirc;
| U+0011C | Ĝ |
gcirc;
| U+0011D | ĝ |
Gcy;
| U+00413 | Г |
gcy;
| U+00433 | г |
Gdot;
| U+00120 | Ġ |
gdot;
| U+00121 | ġ |
gE;
| U+02267 | ≧ |
ge;
| U+02265 | ≥ |
gEl;
| U+02A8C | ⪌ |
gel;
| U+022DB | ⋛ |
geq;
| U+02265 | ≥ |
geqq;
| U+02267 | ≧ |
geqslant;
| U+02A7E | ⩾ |
ges;
| U+02A7E | ⩾ |
gescc;
| U+02AA9 | ⪩ |
gesdot;
| U+02A80 | ⪀ |
gesdoto;
| U+02A82 | ⪂ |
gesdotol;
| U+02A84 | ⪄ |
gesl;
| U+022DB U+0FE00 | ⋛︀ |
gesles;
| U+02A94 | ⪔ |
Gfr;
| U+1D50A | 𝔊 |
gfr;
| U+1D524 | 𝔤 |
Gg;
| U+022D9 | ⋙ |
gg;
| U+0226B | ≫ |
ggg;
| U+022D9 | ⋙ |
gimel;
| U+02137 | ℷ |
GJcy;
| U+00403 | Ѓ |
gjcy;
| U+00453 | ѓ |
gl;
| U+02277 | ≷ |
gla;
| U+02AA5 | ⪥ |
glE;
| U+02A92 | ⪒ |
glj;
| U+02AA4 | ⪤ |
gnap;
| U+02A8A | ⪊ |
gnapprox;
| U+02A8A | ⪊ |
gnE;
| U+02269 | ≩ |
gne;
| U+02A88 | ⪈ |
gneq;
| U+02A88 | ⪈ |
gneqq;
| U+02269 | ≩ |
gnsim;
| U+022E7 | ⋧ |
Gopf;
| U+1D53E | 𝔾 |
gopf;
| U+1D558 | 𝕘 |
grave;
| U+00060 | ` |
GreaterEqual;
| U+02265 | ≥ |
GreaterEqualLess;
| U+022DB | ⋛ |
GreaterFullEqual;
| U+02267 | ≧ |
GreaterGreater;
| U+02AA2 | ⪢ |
GreaterLess;
| U+02277 | ≷ |
GreaterSlantEqual;
| U+02A7E | ⩾ |
GreaterTilde;
| U+02273 | ≳ |
Gscr;
| U+1D4A2 | 𝒢 |
gscr;
| U+0210A | ℊ |
gsim;
| U+02273 | ≳ |
gsime;
| U+02A8E | ⪎ |
gsiml;
| U+02A90 | ⪐ |
GT;
| U+0003E | > |
GT
| U+0003E | > |
Gt;
| U+0226B | ≫ |
gt;
| U+0003E | > |
gt
| U+0003E | > |
gtcc;
| U+02AA7 | ⪧ |
gtcir;
| U+02A7A | ⩺ |
gtdot;
| U+022D7 | ⋗ |
gtlPar;
| U+02995 | ⦕ |
gtquest;
| U+02A7C | ⩼ |
gtrapprox;
| U+02A86 | ⪆ |
gtrarr;
| U+02978 | ⥸ |
gtrdot;
| U+022D7 | ⋗ |
gtreqless;
| U+022DB | ⋛ |
gtreqqless;
| U+02A8C | ⪌ |
gtrless;
| U+02277 | ≷ |
gtrsim;
| U+02273 | ≳ |
gvertneqq;
| U+02269 U+0FE00 | ≩︀ |
gvnE;
| U+02269 U+0FE00 | ≩︀ |
Hacek;
| U+002C7 | ˇ |
hairsp;
| U+0200A | |
half;
| U+000BD | ½ |
hamilt;
| U+0210B | ℋ |
HARDcy;
| U+0042A | Ъ |
hardcy;
| U+0044A | ъ |
hArr;
| U+021D4 | ⇔ |
harr;
| U+02194 | ↔ |
harrcir;
| U+02948 | ⥈ |
harrw;
| U+021AD | ↭ |
Hat;
| U+0005E | ^ |
hbar;
| U+0210F | ℏ |
Hcirc;
| U+00124 | Ĥ |
hcirc;
| U+00125 | ĥ |
hearts;
| U+02665 | ♥ |
heartsuit;
| U+02665 | ♥ |
hellip;
| U+02026 | … |
hercon;
| U+022B9 | ⊹ |
Hfr;
| U+0210C | ℌ |
hfr;
| U+1D525 | 𝔥 |
HilbertSpace;
| U+0210B | ℋ |
hksearow;
| U+02925 | ⤥ |
hkswarow;
| U+02926 | ⤦ |
hoarr;
| U+021FF | ⇿ |
homtht;
| U+0223B | ∻ |
hookleftarrow;
| U+021A9 | ↩ |
hookrightarrow;
| U+021AA | ↪ |
Hopf;
| U+0210D | ℍ |
hopf;
| U+1D559 | 𝕙 |
horbar;
| U+02015 | ― |
HorizontalLine;
| U+02500 | ─ |
Hscr;
| U+0210B | ℋ |
hscr;
| U+1D4BD | 𝒽 |
hslash;
| U+0210F | ℏ |
Hstrok;
| U+00126 | Ħ |
hstrok;
| U+00127 | ħ |
HumpDownHump;
| U+0224E | ≎ |
HumpEqual;
| U+0224F | ≏ |
hybull;
| U+02043 | ⁃ |
hyphen;
| U+02010 | ‐ |
Iacute;
| U+000CD | Í |
Iacute
| U+000CD | Í |
iacute;
| U+000ED | í |
iacute
| U+000ED | í |
ic;
| U+02063 | |
Icirc;
| U+000CE | Î |
Icirc
| U+000CE | Î |
icirc;
| U+000EE | î |
icirc
| U+000EE | î |
Icy;
| U+00418 | И |
icy;
| U+00438 | и |
Idot;
| U+00130 | İ |
IEcy;
| U+00415 | Е |
iecy;
| U+00435 | е |
iexcl;
| U+000A1 | ¡ |
iexcl
| U+000A1 | ¡ |
iff;
| U+021D4 | ⇔ |
Ifr;
| U+02111 | ℑ |
ifr;
| U+1D526 | 𝔦 |
Igrave;
| U+000CC | Ì |
Igrave
| U+000CC | Ì |
igrave;
| U+000EC | ì |
igrave
| U+000EC | ì |
ii;
| U+02148 | ⅈ |
iiiint;
| U+02A0C | ⨌ |
iiint;
| U+0222D | ∭ |
iinfin;
| U+029DC | ⧜ |
iiota;
| U+02129 | ℩ |
IJlig;
| U+00132 | IJ |
ijlig;
| U+00133 | ij |
Im;
| U+02111 | ℑ |
Imacr;
| U+0012A | Ī |
imacr;
| U+0012B | ī |
image;
| U+02111 | ℑ |
ImaginaryI;
| U+02148 | ⅈ |
imagline;
| U+02110 | ℐ |
imagpart;
| U+02111 | ℑ |
imath;
| U+00131 | ı |
imof;
| U+022B7 | ⊷ |
imped;
| U+001B5 | Ƶ |
Implies;
| U+021D2 | ⇒ |
in;
| U+02208 | ∈ |
incare;
| U+02105 | ℅ |
infin;
| U+0221E | ∞ |
infintie;
| U+029DD | ⧝ |
inodot;
| U+00131 | ı |
Int;
| U+0222C | ∬ |
int;
| U+0222B | ∫ |
intcal;
| U+022BA | ⊺ |
integers;
| U+02124 | ℤ |
Integral;
| U+0222B | ∫ |
intercal;
| U+022BA | ⊺ |
Intersection;
| U+022C2 | ⋂ |
intlarhk;
| U+02A17 | ⨗ |
intprod;
| U+02A3C | ⨼ |
InvisibleComma;
| U+02063 | |
InvisibleTimes;
| U+02062 | |
IOcy;
| U+00401 | Ё |
iocy;
| U+00451 | ё |
Iogon;
| U+0012E | Į |
iogon;
| U+0012F | į |
Iopf;
| U+1D540 | 𝕀 |
iopf;
| U+1D55A | 𝕚 |
Iota;
| U+00399 | Ι |
iota;
| U+003B9 | ι |
iprod;
| U+02A3C | ⨼ |
iquest;
| U+000BF | ¿ |
iquest
| U+000BF | ¿ |
Iscr;
| U+02110 | ℐ |
iscr;
| U+1D4BE | 𝒾 |
isin;
| U+02208 | ∈ |
isindot;
| U+022F5 | ⋵ |
isinE;
| U+022F9 | ⋹ |
isins;
| U+022F4 | ⋴ |
isinsv;
| U+022F3 | ⋳ |
isinv;
| U+02208 | ∈ |
it;
| U+02062 | |
Itilde;
| U+00128 | Ĩ |
itilde;
| U+00129 | ĩ |
Iukcy;
| U+00406 | І |
iukcy;
| U+00456 | і |
Iuml;
| U+000CF | Ï |
Iuml
| U+000CF | Ï |
iuml;
| U+000EF | ï |
iuml
| U+000EF | ï |
Jcirc;
| U+00134 | Ĵ |
jcirc;
| U+00135 | ĵ |
Jcy;
| U+00419 | Й |
jcy;
| U+00439 | й |
Jfr;
| U+1D50D | 𝔍 |
jfr;
| U+1D527 | 𝔧 |
jmath;
| U+00237 | ȷ |
Jopf;
| U+1D541 | 𝕁 |
jopf;
| U+1D55B | 𝕛 |
Jscr;
| U+1D4A5 | 𝒥 |
jscr;
| U+1D4BF | 𝒿 |
Jsercy;
| U+00408 | Ј |
jsercy;
| U+00458 | ј |
Jukcy;
| U+00404 | Є |
jukcy;
| U+00454 | є |
Kappa;
| U+0039A | Κ |
kappa;
| U+003BA | κ |
kappav;
| U+003F0 | ϰ |
Kcedil;
| U+00136 | Ķ |
kcedil;
| U+00137 | ķ |
Kcy;
| U+0041A | К |
kcy;
| U+0043A | к |
Kfr;
| U+1D50E | 𝔎 |
kfr;
| U+1D528 | 𝔨 |
kgreen;
| U+00138 | ĸ |
KHcy;
| U+00425 | Х |
khcy;
| U+00445 | х |
KJcy;
| U+0040C | Ќ |
kjcy;
| U+0045C | ќ |
Kopf;
| U+1D542 | 𝕂 |
kopf;
| U+1D55C | 𝕜 |
Kscr;
| U+1D4A6 | 𝒦 |
kscr;
| U+1D4C0 | 𝓀 |
lAarr;
| U+021DA | ⇚ |
Lacute;
| U+00139 | Ĺ |
lacute;
| U+0013A | ĺ |
laemptyv;
| U+029B4 | ⦴ |
lagran;
| U+02112 | ℒ |
Lambda;
| U+0039B | Λ |
lambda;
| U+003BB | λ |
Lang;
| U+027EA | ⟪ |
lang;
| U+027E8 | ⟨ |
langd;
| U+02991 | ⦑ |
langle;
| U+027E8 | ⟨ |
lap;
| U+02A85 | ⪅ |
Laplacetrf;
| U+02112 | ℒ |
laquo;
| U+000AB | « |
laquo
| U+000AB | « |
Larr;
| U+0219E | ↞ |
lArr;
| U+021D0 | ⇐ |
larr;
| U+02190 | ← |
larrb;
| U+021E4 | ⇤ |
larrbfs;
| U+0291F | ⤟ |
larrfs;
| U+0291D | ⤝ |
larrhk;
| U+021A9 | ↩ |
larrlp;
| U+021AB | ↫ |
larrpl;
| U+02939 | ⤹ |
larrsim;
| U+02973 | ⥳ |
larrtl;
| U+021A2 | ↢ |
lat;
| U+02AAB | ⪫ |
lAtail;
| U+0291B | ⤛ |
latail;
| U+02919 | ⤙ |
late;
| U+02AAD | ⪭ |
lates;
| U+02AAD U+0FE00 | ⪭︀ |
lBarr;
| U+0290E | ⤎ |
lbarr;
| U+0290C | ⤌ |
lbbrk;
| U+02772 | ❲ |
lbrace;
| U+0007B | { |
lbrack;
| U+0005B | [ |
lbrke;
| U+0298B | ⦋ |
lbrksld;
| U+0298F | ⦏ |
lbrkslu;
| U+0298D | ⦍ |
Lcaron;
| U+0013D | Ľ |
lcaron;
| U+0013E | ľ |
Lcedil;
| U+0013B | Ļ |
lcedil;
| U+0013C | ļ |
lceil;
| U+02308 | ⌈ |
lcub;
| U+0007B | { |
Lcy;
| U+0041B | Л |
lcy;
| U+0043B | л |
ldca;
| U+02936 | ⤶ |
ldquo;
| U+0201C | “ |
ldquor;
| U+0201E | „ |
ldrdhar;
| U+02967 | ⥧ |
ldrushar;
| U+0294B | ⥋ |
ldsh;
| U+021B2 | ↲ |
lE;
| U+02266 | ≦ |
le;
| U+02264 | ≤ |
LeftAngleBracket;
| U+027E8 | ⟨ |
LeftArrow;
| U+02190 | ← |
Leftarrow;
| U+021D0 | ⇐ |
leftarrow;
| U+02190 | ← |
LeftArrowBar;
| U+021E4 | ⇤ |
LeftArrowRightArrow;
| U+021C6 | ⇆ |
leftarrowtail;
| U+021A2 | ↢ |
LeftCeiling;
| U+02308 | ⌈ |
LeftDoubleBracket;
| U+027E6 | ⟦ |
LeftDownTeeVector;
| U+02961 | ⥡ |
LeftDownVector;
| U+021C3 | ⇃ |
LeftDownVectorBar;
| U+02959 | ⥙ |
LeftFloor;
| U+0230A | ⌊ |
leftharpoondown;
| U+021BD | ↽ |
leftharpoonup;
| U+021BC | ↼ |
leftleftarrows;
| U+021C7 | ⇇ |
LeftRightArrow;
| U+02194 | ↔ |
Leftrightarrow;
| U+021D4 | ⇔ |
leftrightarrow;
| U+02194 | ↔ |
leftrightarrows;
| U+021C6 | ⇆ |
leftrightharpoons;
| U+021CB | ⇋ |
leftrightsquigarrow;
| U+021AD | ↭ |
LeftRightVector;
| U+0294E | ⥎ |
LeftTee;
| U+022A3 | ⊣ |
LeftTeeArrow;
| U+021A4 | ↤ |
LeftTeeVector;
| U+0295A | ⥚ |
leftthreetimes;
| U+022CB | ⋋ |
LeftTriangle;
| U+022B2 | ⊲ |
LeftTriangleBar;
| U+029CF | ⧏ |
LeftTriangleEqual;
| U+022B4 | ⊴ |
LeftUpDownVector;
| U+02951 | ⥑ |
LeftUpTeeVector;
| U+02960 | ⥠ |
LeftUpVector;
| U+021BF | ↿ |
LeftUpVectorBar;
| U+02958 | ⥘ |
LeftVector;
| U+021BC | ↼ |
LeftVectorBar;
| U+02952 | ⥒ |
lEg;
| U+02A8B | ⪋ |
leg;
| U+022DA | ⋚ |
leq;
| U+02264 | ≤ |
leqq;
| U+02266 | ≦ |
leqslant;
| U+02A7D | ⩽ |
les;
| U+02A7D | ⩽ |
lescc;
| U+02AA8 | ⪨ |
lesdot;
| U+02A7F | ⩿ |
lesdoto;
| U+02A81 | ⪁ |
lesdotor;
| U+02A83 | ⪃ |
lesg;
| U+022DA U+0FE00 | ⋚︀ |
lesges;
| U+02A93 | ⪓ |
lessapprox;
| U+02A85 | ⪅ |
lessdot;
| U+022D6 | ⋖ |
lesseqgtr;
| U+022DA | ⋚ |
lesseqqgtr;
| U+02A8B | ⪋ |
LessEqualGreater;
| U+022DA | ⋚ |
LessFullEqual;
| U+02266 | ≦ |
LessGreater;
| U+02276 | ≶ |
lessgtr;
| U+02276 | ≶ |
LessLess;
| U+02AA1 | ⪡ |
lesssim;
| U+02272 | ≲ |
LessSlantEqual;
| U+02A7D | ⩽ |
LessTilde;
| U+02272 | ≲ |
lfisht;
| U+0297C | ⥼ |
lfloor;
| U+0230A | ⌊ |
Lfr;
| U+1D50F | 𝔏 |
lfr;
| U+1D529 | 𝔩 |
lg;
| U+02276 | ≶ |
lgE;
| U+02A91 | ⪑ |
lHar;
| U+02962 | ⥢ |
lhard;
| U+021BD | ↽ |
lharu;
| U+021BC | ↼ |
lharul;
| U+0296A | ⥪ |
lhblk;
| U+02584 | ▄ |
LJcy;
| U+00409 | Љ |
ljcy;
| U+00459 | љ |
Ll;
| U+022D8 | ⋘ |
ll;
| U+0226A | ≪ |
llarr;
| U+021C7 | ⇇ |
llcorner;
| U+0231E | ⌞ |
Lleftarrow;
| U+021DA | ⇚ |
llhard;
| U+0296B | ⥫ |
lltri;
| U+025FA | ◺ |
Lmidot;
| U+0013F | Ŀ |
lmidot;
| U+00140 | ŀ |
lmoust;
| U+023B0 | ⎰ |
lmoustache;
| U+023B0 | ⎰ |
lnap;
| U+02A89 | ⪉ |
lnapprox;
| U+02A89 | ⪉ |
lnE;
| U+02268 | ≨ |
lne;
| U+02A87 | ⪇ |
lneq;
| U+02A87 | ⪇ |
lneqq;
| U+02268 | ≨ |
lnsim;
| U+022E6 | ⋦ |
loang;
| U+027EC | ⟬ |
loarr;
| U+021FD | ⇽ |
lobrk;
| U+027E6 | ⟦ |
LongLeftArrow;
| U+027F5 | ⟵ |
Longleftarrow;
| U+027F8 | ⟸ |
longleftarrow;
| U+027F5 | ⟵ |
LongLeftRightArrow;
| U+027F7 | ⟷ |
Longleftrightarrow;
| U+027FA | ⟺ |
longleftrightarrow;
| U+027F7 | ⟷ |
longmapsto;
| U+027FC | ⟼ |
LongRightArrow;
| U+027F6 | ⟶ |
Longrightarrow;
| U+027F9 | ⟹ |
longrightarrow;
| U+027F6 | ⟶ |
looparrowleft;
| U+021AB | ↫ |
looparrowright;
| U+021AC | ↬ |
lopar;
| U+02985 | ⦅ |
Lopf;
| U+1D543 | 𝕃 |
lopf;
| U+1D55D | 𝕝 |
loplus;
| U+02A2D | ⨭ |
lotimes;
| U+02A34 | ⨴ |
lowast;
| U+02217 | ∗ |
lowbar;
| U+0005F | _ |
LowerLeftArrow;
| U+02199 | ↙ |
LowerRightArrow;
| U+02198 | ↘ |
loz;
| U+025CA | ◊ |
lozenge;
| U+025CA | ◊ |
lozf;
| U+029EB | ⧫ |
lpar;
| U+00028 | ( |
lparlt;
| U+02993 | ⦓ |
lrarr;
| U+021C6 | ⇆ |
lrcorner;
| U+0231F | ⌟ |
lrhar;
| U+021CB | ⇋ |
lrhard;
| U+0296D | ⥭ |
lrm;
| U+0200E | |
lrtri;
| U+022BF | ⊿ |
lsaquo;
| U+02039 | ‹ |
Lscr;
| U+02112 | ℒ |
lscr;
| U+1D4C1 | 𝓁 |
Lsh;
| U+021B0 | ↰ |
lsh;
| U+021B0 | ↰ |
lsim;
| U+02272 | ≲ |
lsime;
| U+02A8D | ⪍ |
lsimg;
| U+02A8F | ⪏ |
lsqb;
| U+0005B | [ |
lsquo;
| U+02018 | ‘ |
lsquor;
| U+0201A | ‚ |
Lstrok;
| U+00141 | Ł |
lstrok;
| U+00142 | ł |
LT;
| U+0003C | < |
LT
| U+0003C | < |
Lt;
| U+0226A | ≪ |
lt;
| U+0003C | < |
lt
| U+0003C | < |
ltcc;
| U+02AA6 | ⪦ |
ltcir;
| U+02A79 | ⩹ |
ltdot;
| U+022D6 | ⋖ |
lthree;
| U+022CB | ⋋ |
ltimes;
| U+022C9 | ⋉ |
ltlarr;
| U+02976 | ⥶ |
ltquest;
| U+02A7B | ⩻ |
ltri;
| U+025C3 | ◃ |
ltrie;
| U+022B4 | ⊴ |
ltrif;
| U+025C2 | ◂ |
ltrPar;
| U+02996 | ⦖ |
lurdshar;
| U+0294A | ⥊ |
luruhar;
| U+02966 | ⥦ |
lvertneqq;
| U+02268 U+0FE00 | ≨︀ |
lvnE;
| U+02268 U+0FE00 | ≨︀ |
macr;
| U+000AF | ¯ |
macr
| U+000AF | ¯ |
male;
| U+02642 | ♂ |
malt;
| U+02720 | ✠ |
maltese;
| U+02720 | ✠ |
Map;
| U+02905 | ⤅ |
map;
| U+021A6 | ↦ |
mapsto;
| U+021A6 | ↦ |
mapstodown;
| U+021A7 | ↧ |
mapstoleft;
| U+021A4 | ↤ |
mapstoup;
| U+021A5 | ↥ |
marker;
| U+025AE | ▮ |
mcomma;
| U+02A29 | ⨩ |
Mcy;
| U+0041C | М |
mcy;
| U+0043C | м |
mdash;
| U+02014 | — |
mDDot;
| U+0223A | ∺ |
measuredangle;
| U+02221 | ∡ |
MediumSpace;
| U+0205F | |
Mellintrf;
| U+02133 | ℳ |
Mfr;
| U+1D510 | 𝔐 |
mfr;
| U+1D52A | 𝔪 |
mho;
| U+02127 | ℧ |
micro;
| U+000B5 | µ |
micro
| U+000B5 | µ |
mid;
| U+02223 | ∣ |
midast;
| U+0002A | * |
midcir;
| U+02AF0 | ⫰ |
middot;
| U+000B7 | · |
middot
| U+000B7 | · |
minus;
| U+02212 | − |
minusb;
| U+0229F | ⊟ |
minusd;
| U+02238 | ∸ |
minusdu;
| U+02A2A | ⨪ |
MinusPlus;
| U+02213 | ∓ |
mlcp;
| U+02ADB | ⫛ |
mldr;
| U+02026 | … |
mnplus;
| U+02213 | ∓ |
models;
| U+022A7 | ⊧ |
Mopf;
| U+1D544 | 𝕄 |
mopf;
| U+1D55E | 𝕞 |
mp;
| U+02213 | ∓ |
Mscr;
| U+02133 | ℳ |
mscr;
| U+1D4C2 | 𝓂 |
mstpos;
| U+0223E | ∾ |
Mu;
| U+0039C | Μ |
mu;
| U+003BC | μ |
multimap;
| U+022B8 | ⊸ |
mumap;
| U+022B8 | ⊸ |
nabla;
| U+02207 | ∇ |
Nacute;
| U+00143 | Ń |
nacute;
| U+00144 | ń |
nang;
| U+02220 U+020D2 | ∠⃒ |
nap;
| U+02249 | ≉ |
napE;
| U+02A70 U+00338 | ⩰̸ |
napid;
| U+0224B U+00338 | ≋̸ |
napos;
| U+00149 | ʼn |
napprox;
| U+02249 | ≉ |
natur;
| U+0266E | ♮ |
natural;
| U+0266E | ♮ |
naturals;
| U+02115 | ℕ |
nbsp;
| U+000A0 | |
nbsp
| U+000A0 | |
nbump;
| U+0224E U+00338 | ≎̸ |
nbumpe;
| U+0224F U+00338 | ≏̸ |
ncap;
| U+02A43 | ⩃ |
Ncaron;
| U+00147 | Ň |
ncaron;
| U+00148 | ň |
Ncedil;
| U+00145 | Ņ |
ncedil;
| U+00146 | ņ |
ncong;
| U+02247 | ≇ |
ncongdot;
| U+02A6D U+00338 | ⩭̸ |
ncup;
| U+02A42 | ⩂ |
Ncy;
| U+0041D | Н |
ncy;
| U+0043D | н |
ndash;
| U+02013 | – |
ne;
| U+02260 | ≠ |
nearhk;
| U+02924 | ⤤ |
neArr;
| U+021D7 | ⇗ |
nearr;
| U+02197 | ↗ |
nearrow;
| U+02197 | ↗ |
nedot;
| U+02250 U+00338 | ≐̸ |
NegativeMediumSpace;
| U+0200B | |
NegativeThickSpace;
| U+0200B | |
NegativeThinSpace;
| U+0200B | |
NegativeVeryThinSpace;
| U+0200B | |
nequiv;
| U+02262 | ≢ |
nesear;
| U+02928 | ⤨ |
nesim;
| U+02242 U+00338 | ≂̸ |
NestedGreaterGreater;
| U+0226B | ≫ |
NestedLessLess;
| U+0226A | ≪ |
NewLine;
| U+0000A | ␊ |
nexist;
| U+02204 | ∄ |
nexists;
| U+02204 | ∄ |
Nfr;
| U+1D511 | 𝔑 |
nfr;
| U+1D52B | 𝔫 |
ngE;
| U+02267 U+00338 | ≧̸ |
nge;
| U+02271 | ≱ |
ngeq;
| U+02271 | ≱ |
ngeqq;
| U+02267 U+00338 | ≧̸ |
ngeqslant;
| U+02A7E U+00338 | ⩾̸ |
nges;
| U+02A7E U+00338 | ⩾̸ |
nGg;
| U+022D9 U+00338 | ⋙̸ |
ngsim;
| U+02275 | ≵ |
nGt;
| U+0226B U+020D2 | ≫⃒ |
ngt;
| U+0226F | ≯ |
ngtr;
| U+0226F | ≯ |
nGtv;
| U+0226B U+00338 | ≫̸ |
nhArr;
| U+021CE | ⇎ |
nharr;
| U+021AE | ↮ |
nhpar;
| U+02AF2 | ⫲ |
ni;
| U+0220B | ∋ |
nis;
| U+022FC | ⋼ |
nisd;
| U+022FA | ⋺ |
niv;
| U+0220B | ∋ |
NJcy;
| U+0040A | Њ |
njcy;
| U+0045A | њ |
nlArr;
| U+021CD | ⇍ |
nlarr;
| U+0219A | ↚ |
nldr;
| U+02025 | ‥ |
nlE;
| U+02266 U+00338 | ≦̸ |
nle;
| U+02270 | ≰ |
nLeftarrow;
| U+021CD | ⇍ |
nleftarrow;
| U+0219A | ↚ |
nLeftrightarrow;
| U+021CE | ⇎ |
nleftrightarrow;
| U+021AE | ↮ |
nleq;
| U+02270 | ≰ |
nleqq;
| U+02266 U+00338 | ≦̸ |
nleqslant;
| U+02A7D U+00338 | ⩽̸ |
nles;
| U+02A7D U+00338 | ⩽̸ |
nless;
| U+0226E | ≮ |
nLl;
| U+022D8 U+00338 | ⋘̸ |
nlsim;
| U+02274 | ≴ |
nLt;
| U+0226A U+020D2 | ≪⃒ |
nlt;
| U+0226E | ≮ |
nltri;
| U+022EA | ⋪ |
nltrie;
| U+022EC | ⋬ |
nLtv;
| U+0226A U+00338 | ≪̸ |
nmid;
| U+02224 | ∤ |
NoBreak;
| U+02060 | |
NonBreakingSpace;
| U+000A0 | |
Nopf;
| U+02115 | ℕ |
nopf;
| U+1D55F | 𝕟 |
Not;
| U+02AEC | ⫬ |
not;
| U+000AC | ¬ |
not
| U+000AC | ¬ |
NotCongruent;
| U+02262 | ≢ |
NotCupCap;
| U+0226D | ≭ |
NotDoubleVerticalBar;
| U+02226 | ∦ |
NotElement;
| U+02209 | ∉ |
NotEqual;
| U+02260 | ≠ |
NotEqualTilde;
| U+02242 U+00338 | ≂̸ |
NotExists;
| U+02204 | ∄ |
NotGreater;
| U+0226F | ≯ |
NotGreaterEqual;
| U+02271 | ≱ |
NotGreaterFullEqual;
| U+02267 U+00338 | ≧̸ |
NotGreaterGreater;
| U+0226B U+00338 | ≫̸ |
NotGreaterLess;
| U+02279 | ≹ |
NotGreaterSlantEqual;
| U+02A7E U+00338 | ⩾̸ |
NotGreaterTilde;
| U+02275 | ≵ |
NotHumpDownHump;
| U+0224E U+00338 | ≎̸ |
NotHumpEqual;
| U+0224F U+00338 | ≏̸ |
notin;
| U+02209 | ∉ |
notindot;
| U+022F5 U+00338 | ⋵̸ |
notinE;
| U+022F9 U+00338 | ⋹̸ |
notinva;
| U+02209 | ∉ |
notinvb;
| U+022F7 | ⋷ |
notinvc;
| U+022F6 | ⋶ |
NotLeftTriangle;
| U+022EA | ⋪ |
NotLeftTriangleBar;
| U+029CF U+00338 | ⧏̸ |
NotLeftTriangleEqual;
| U+022EC | ⋬ |
NotLess;
| U+0226E | ≮ |
NotLessEqual;
| U+02270 | ≰ |
NotLessGreater;
| U+02278 | ≸ |
NotLessLess;
| U+0226A U+00338 | ≪̸ |
NotLessSlantEqual;
| U+02A7D U+00338 | ⩽̸ |
NotLessTilde;
| U+02274 | ≴ |
NotNestedGreaterGreater;
| U+02AA2 U+00338 | ⪢̸ |
NotNestedLessLess;
| U+02AA1 U+00338 | ⪡̸ |
notni;
| U+0220C | ∌ |
notniva;
| U+0220C | ∌ |
notnivb;
| U+022FE | ⋾ |
notnivc;
| U+022FD | ⋽ |
NotPrecedes;
| U+02280 | ⊀ |
NotPrecedesEqual;
| U+02AAF U+00338 | ⪯̸ |
NotPrecedesSlantEqual;
| U+022E0 | ⋠ |
NotReverseElement;
| U+0220C | ∌ |
NotRightTriangle;
| U+022EB | ⋫ |
NotRightTriangleBar;
| U+029D0 U+00338 | ⧐̸ |
NotRightTriangleEqual;
| U+022ED | ⋭ |
NotSquareSubset;
| U+0228F U+00338 | ⊏̸ |
NotSquareSubsetEqual;
| U+022E2 | ⋢ |
NotSquareSuperset;
| U+02290 U+00338 | ⊐̸ |
NotSquareSupersetEqual;
| U+022E3 | ⋣ |
NotSubset;
| U+02282 U+020D2 | ⊂⃒ |
NotSubsetEqual;
| U+02288 | ⊈ |
NotSucceeds;
| U+02281 | ⊁ |
NotSucceedsEqual;
| U+02AB0 U+00338 | ⪰̸ |
NotSucceedsSlantEqual;
| U+022E1 | ⋡ |
NotSucceedsTilde;
| U+0227F U+00338 | ≿̸ |
NotSuperset;
| U+02283 U+020D2 | ⊃⃒ |
NotSupersetEqual;
| U+02289 | ⊉ |
NotTilde;
| U+02241 | ≁ |
NotTildeEqual;
| U+02244 | ≄ |
NotTildeFullEqual;
| U+02247 | ≇ |
NotTildeTilde;
| U+02249 | ≉ |
NotVerticalBar;
| U+02224 | ∤ |
npar;
| U+02226 | ∦ |
nparallel;
| U+02226 | ∦ |
nparsl;
| U+02AFD U+020E5 | ⫽⃥ |
npart;
| U+02202 U+00338 | ∂̸ |
npolint;
| U+02A14 | ⨔ |
npr;
| U+02280 | ⊀ |
nprcue;
| U+022E0 | ⋠ |
npre;
| U+02AAF U+00338 | ⪯̸ |
nprec;
| U+02280 | ⊀ |
npreceq;
| U+02AAF U+00338 | ⪯̸ |
nrArr;
| U+021CF | ⇏ |
nrarr;
| U+0219B | ↛ |
nrarrc;
| U+02933 U+00338 | ⤳̸ |
nrarrw;
| U+0219D U+00338 | ↝̸ |
nRightarrow;
| U+021CF | ⇏ |
nrightarrow;
| U+0219B | ↛ |
nrtri;
| U+022EB | ⋫ |
nrtrie;
| U+022ED | ⋭ |
nsc;
| U+02281 | ⊁ |
nsccue;
| U+022E1 | ⋡ |
nsce;
| U+02AB0 U+00338 | ⪰̸ |
Nscr;
| U+1D4A9 | 𝒩 |
nscr;
| U+1D4C3 | 𝓃 |
nshortmid;
| U+02224 | ∤ |
nshortparallel;
| U+02226 | ∦ |
nsim;
| U+02241 | ≁ |
nsime;
| U+02244 | ≄ |
nsimeq;
| U+02244 | ≄ |
nsmid;
| U+02224 | ∤ |
nspar;
| U+02226 | ∦ |
nsqsube;
| U+022E2 | ⋢ |
nsqsupe;
| U+022E3 | ⋣ |
nsub;
| U+02284 | ⊄ |
nsubE;
| U+02AC5 U+00338 | ⫅̸ |
nsube;
| U+02288 | ⊈ |
nsubset;
| U+02282 U+020D2 | ⊂⃒ |
nsubseteq;
| U+02288 | ⊈ |
nsubseteqq;
| U+02AC5 U+00338 | ⫅̸ |
nsucc;
| U+02281 | ⊁ |
nsucceq;
| U+02AB0 U+00338 | ⪰̸ |
nsup;
| U+02285 | ⊅ |
nsupE;
| U+02AC6 U+00338 | ⫆̸ |
nsupe;
| U+02289 | ⊉ |
nsupset;
| U+02283 U+020D2 | ⊃⃒ |
nsupseteq;
| U+02289 | ⊉ |
nsupseteqq;
| U+02AC6 U+00338 | ⫆̸ |
ntgl;
| U+02279 | ≹ |
Ntilde;
| U+000D1 | Ñ |
Ntilde
| U+000D1 | Ñ |
ntilde;
| U+000F1 | ñ |
ntilde
| U+000F1 | ñ |
ntlg;
| U+02278 | ≸ |
ntriangleleft;
| U+022EA | ⋪ |
ntrianglelefteq;
| U+022EC | ⋬ |
ntriangleright;
| U+022EB | ⋫ |
ntrianglerighteq;
| U+022ED | ⋭ |
Nu;
| U+0039D | Ν |
nu;
| U+003BD | ν |
num;
| U+00023 | # |
numero;
| U+02116 | № |
numsp;
| U+02007 | |
nvap;
| U+0224D U+020D2 | ≍⃒ |
nVDash;
| U+022AF | ⊯ |
nVdash;
| U+022AE | ⊮ |
nvDash;
| U+022AD | ⊭ |
nvdash;
| U+022AC | ⊬ |
nvge;
| U+02265 U+020D2 | ≥⃒ |
nvgt;
| U+0003E U+020D2 | >⃒ |
nvHarr;
| U+02904 | ⤄ |
nvinfin;
| U+029DE | ⧞ |
nvlArr;
| U+02902 | ⤂ |
nvle;
| U+02264 U+020D2 | ≤⃒ |
nvlt;
| U+0003C U+020D2 | <⃒ |
nvltrie;
| U+022B4 U+020D2 | ⊴⃒ |
nvrArr;
| U+02903 | ⤃ |
nvrtrie;
| U+022B5 U+020D2 | ⊵⃒ |
nvsim;
| U+0223C U+020D2 | ∼⃒ |
nwarhk;
| U+02923 | ⤣ |
nwArr;
| U+021D6 | ⇖ |
nwarr;
| U+02196 | ↖ |
nwarrow;
| U+02196 | ↖ |
nwnear;
| U+02927 | ⤧ |
Oacute;
| U+000D3 | Ó |
Oacute
| U+000D3 | Ó |
oacute;
| U+000F3 | ó |
oacute
| U+000F3 | ó |
oast;
| U+0229B | ⊛ |
ocir;
| U+0229A | ⊚ |
Ocirc;
| U+000D4 | Ô |
Ocirc
| U+000D4 | Ô |
ocirc;
| U+000F4 | ô |
ocirc
| U+000F4 | ô |
Ocy;
| U+0041E | О |
ocy;
| U+0043E | о |
odash;
| U+0229D | ⊝ |
Odblac;
| U+00150 | Ő |
odblac;
| U+00151 | ő |
odiv;
| U+02A38 | ⨸ |
odot;
| U+02299 | ⊙ |
odsold;
| U+029BC | ⦼ |
OElig;
| U+00152 | Œ |
oelig;
| U+00153 | œ |
ofcir;
| U+029BF | ⦿ |
Ofr;
| U+1D512 | 𝔒 |
ofr;
| U+1D52C | 𝔬 |
ogon;
| U+002DB | ˛ |
Ograve;
| U+000D2 | Ò |
Ograve
| U+000D2 | Ò |
ograve;
| U+000F2 | ò |
ograve
| U+000F2 | ò |
ogt;
| U+029C1 | ⧁ |
ohbar;
| U+029B5 | ⦵ |
ohm;
| U+003A9 | Ω |
oint;
| U+0222E | ∮ |
olarr;
| U+021BA | ↺ |
olcir;
| U+029BE | ⦾ |
olcross;
| U+029BB | ⦻ |
oline;
| U+0203E | ‾ |
olt;
| U+029C0 | ⧀ |
Omacr;
| U+0014C | Ō |
omacr;
| U+0014D | ō |
Omega;
| U+003A9 | Ω |
omega;
| U+003C9 | ω |
Omicron;
| U+0039F | Ο |
omicron;
| U+003BF | ο |
omid;
| U+029B6 | ⦶ |
ominus;
| U+02296 | ⊖ |
Oopf;
| U+1D546 | 𝕆 |
oopf;
| U+1D560 | 𝕠 |
opar;
| U+029B7 | ⦷ |
OpenCurlyDoubleQuote;
| U+0201C | “ |
OpenCurlyQuote;
| U+02018 | ‘ |
operp;
| U+029B9 | ⦹ |
oplus;
| U+02295 | ⊕ |
Or;
| U+02A54 | ⩔ |
or;
| U+02228 | ∨ |
orarr;
| U+021BB | ↻ |
ord;
| U+02A5D | ⩝ |
order;
| U+02134 | ℴ |
orderof;
| U+02134 | ℴ |
ordf;
| U+000AA | ª |
ordf
| U+000AA | ª |
ordm;
| U+000BA | º |
ordm
| U+000BA | º |
origof;
| U+022B6 | ⊶ |
oror;
| U+02A56 | ⩖ |
orslope;
| U+02A57 | ⩗ |
orv;
| U+02A5B | ⩛ |
oS;
| U+024C8 | Ⓢ |
Oscr;
| U+1D4AA | 𝒪 |
oscr;
| U+02134 | ℴ |
Oslash;
| U+000D8 | Ø |
Oslash
| U+000D8 | Ø |
oslash;
| U+000F8 | ø |
oslash
| U+000F8 | ø |
osol;
| U+02298 | ⊘ |
Otilde;
| U+000D5 | Õ |
Otilde
| U+000D5 | Õ |
otilde;
| U+000F5 | õ |
otilde
| U+000F5 | õ |
Otimes;
| U+02A37 | ⨷ |
otimes;
| U+02297 | ⊗ |
otimesas;
| U+02A36 | ⨶ |
Ouml;
| U+000D6 | Ö |
Ouml
| U+000D6 | Ö |
ouml;
| U+000F6 | ö |
ouml
| U+000F6 | ö |
ovbar;
| U+0233D | ⌽ |
OverBar;
| U+0203E | ‾ |
OverBrace;
| U+023DE | ⏞ |
OverBracket;
| U+023B4 | ⎴ |
OverParenthesis;
| U+023DC | ⏜ |
par;
| U+02225 | ∥ |
para;
| U+000B6 | ¶ |
para
| U+000B6 | ¶ |
parallel;
| U+02225 | ∥ |
parsim;
| U+02AF3 | ⫳ |
parsl;
| U+02AFD | ⫽ |
part;
| U+02202 | ∂ |
PartialD;
| U+02202 | ∂ |
Pcy;
| U+0041F | П |
pcy;
| U+0043F | п |
percnt;
| U+00025 | % |
period;
| U+0002E | . |
permil;
| U+02030 | ‰ |
perp;
| U+022A5 | ⊥ |
pertenk;
| U+02031 | ‱ |
Pfr;
| U+1D513 | 𝔓 |
pfr;
| U+1D52D | 𝔭 |
Phi;
| U+003A6 | Φ |
phi;
| U+003C6 | φ |
phiv;
| U+003D5 | ϕ |
phmmat;
| U+02133 | ℳ |
phone;
| U+0260E | ☎ |
Pi;
| U+003A0 | Π |
pi;
| U+003C0 | π |
pitchfork;
| U+022D4 | ⋔ |
piv;
| U+003D6 | ϖ |
planck;
| U+0210F | ℏ |
planckh;
| U+0210E | ℎ |
plankv;
| U+0210F | ℏ |
plus;
| U+0002B | + |
plusacir;
| U+02A23 | ⨣ |
plusb;
| U+0229E | ⊞ |
pluscir;
| U+02A22 | ⨢ |
plusdo;
| U+02214 | ∔ |
plusdu;
| U+02A25 | ⨥ |
pluse;
| U+02A72 | ⩲ |
PlusMinus;
| U+000B1 | ± |
plusmn;
| U+000B1 | ± |
plusmn
| U+000B1 | ± |
plussim;
| U+02A26 | ⨦ |
plustwo;
| U+02A27 | ⨧ |
pm;
| U+000B1 | ± |
Poincareplane;
| U+0210C | ℌ |
pointint;
| U+02A15 | ⨕ |
Popf;
| U+02119 | ℙ |
popf;
| U+1D561 | 𝕡 |
pound;
| U+000A3 | £ |
pound
| U+000A3 | £ |
Pr;
| U+02ABB | ⪻ |
pr;
| U+0227A | ≺ |
prap;
| U+02AB7 | ⪷ |
prcue;
| U+0227C | ≼ |
prE;
| U+02AB3 | ⪳ |
pre;
| U+02AAF | ⪯ |
prec;
| U+0227A | ≺ |
precapprox;
| U+02AB7 | ⪷ |
preccurlyeq;
| U+0227C | ≼ |
Precedes;
| U+0227A | ≺ |
PrecedesEqual;
| U+02AAF | ⪯ |
PrecedesSlantEqual;
| U+0227C | ≼ |
PrecedesTilde;
| U+0227E | ≾ |
preceq;
| U+02AAF | ⪯ |
precnapprox;
| U+02AB9 | ⪹ |
precneqq;
| U+02AB5 | ⪵ |
precnsim;
| U+022E8 | ⋨ |
precsim;
| U+0227E | ≾ |
Prime;
| U+02033 | ″ |
prime;
| U+02032 | ′ |
primes;
| U+02119 | ℙ |
prnap;
| U+02AB9 | ⪹ |
prnE;
| U+02AB5 | ⪵ |
prnsim;
| U+022E8 | ⋨ |
prod;
| U+0220F | ∏ |
Product;
| U+0220F | ∏ |
profalar;
| U+0232E | ⌮ |
profline;
| U+02312 | ⌒ |
profsurf;
| U+02313 | ⌓ |
prop;
| U+0221D | ∝ |
Proportion;
| U+02237 | ∷ |
Proportional;
| U+0221D | ∝ |
propto;
| U+0221D | ∝ |
prsim;
| U+0227E | ≾ |
prurel;
| U+022B0 | ⊰ |
Pscr;
| U+1D4AB | 𝒫 |
pscr;
| U+1D4C5 | 𝓅 |
Psi;
| U+003A8 | Ψ |
psi;
| U+003C8 | ψ |
puncsp;
| U+02008 | |
Qfr;
| U+1D514 | 𝔔 |
qfr;
| U+1D52E | 𝔮 |
qint;
| U+02A0C | ⨌ |
Qopf;
| U+0211A | ℚ |
qopf;
| U+1D562 | 𝕢 |
qprime;
| U+02057 | ⁗ |
Qscr;
| U+1D4AC | 𝒬 |
qscr;
| U+1D4C6 | 𝓆 |
quaternions;
| U+0210D | ℍ |
quatint;
| U+02A16 | ⨖ |
quest;
| U+0003F | ? |
questeq;
| U+0225F | ≟ |
QUOT;
| U+00022 | " |
QUOT
| U+00022 | " |
quot;
| U+00022 | " |
quot
| U+00022 | " |
rAarr;
| U+021DB | ⇛ |
race;
| U+0223D U+00331 | ∽̱ |
Racute;
| U+00154 | Ŕ |
racute;
| U+00155 | ŕ |
radic;
| U+0221A | √ |
raemptyv;
| U+029B3 | ⦳ |
Rang;
| U+027EB | ⟫ |
rang;
| U+027E9 | ⟩ |
rangd;
| U+02992 | ⦒ |
range;
| U+029A5 | ⦥ |
rangle;
| U+027E9 | ⟩ |
raquo;
| U+000BB | » |
raquo
| U+000BB | » |
Rarr;
| U+021A0 | ↠ |
rArr;
| U+021D2 | ⇒ |
rarr;
| U+02192 | → |
rarrap;
| U+02975 | ⥵ |
rarrb;
| U+021E5 | ⇥ |
rarrbfs;
| U+02920 | ⤠ |
rarrc;
| U+02933 | ⤳ |
rarrfs;
| U+0291E | ⤞ |
rarrhk;
| U+021AA | ↪ |
rarrlp;
| U+021AC | ↬ |
rarrpl;
| U+02945 | ⥅ |
rarrsim;
| U+02974 | ⥴ |
Rarrtl;
| U+02916 | ⤖ |
rarrtl;
| U+021A3 | ↣ |
rarrw;
| U+0219D | ↝ |
rAtail;
| U+0291C | ⤜ |
ratail;
| U+0291A | ⤚ |
ratio;
| U+02236 | ∶ |
rationals;
| U+0211A | ℚ |
RBarr;
| U+02910 | ⤐ |
rBarr;
| U+0290F | ⤏ |
rbarr;
| U+0290D | ⤍ |
rbbrk;
| U+02773 | ❳ |
rbrace;
| U+0007D | } |
rbrack;
| U+0005D | ] |
rbrke;
| U+0298C | ⦌ |
rbrksld;
| U+0298E | ⦎ |
rbrkslu;
| U+02990 | ⦐ |
Rcaron;
| U+00158 | Ř |
rcaron;
| U+00159 | ř |
Rcedil;
| U+00156 | Ŗ |
rcedil;
| U+00157 | ŗ |
rceil;
| U+02309 | ⌉ |
rcub;
| U+0007D | } |
Rcy;
| U+00420 | Р |
rcy;
| U+00440 | р |
rdca;
| U+02937 | ⤷ |
rdldhar;
| U+02969 | ⥩ |
rdquo;
| U+0201D | ” |
rdquor;
| U+0201D | ” |
rdsh;
| U+021B3 | ↳ |
Re;
| U+0211C | ℜ |
real;
| U+0211C | ℜ |
realine;
| U+0211B | ℛ |
realpart;
| U+0211C | ℜ |
reals;
| U+0211D | ℝ |
rect;
| U+025AD | ▭ |
REG;
| U+000AE | ® |
REG
| U+000AE | ® |
reg;
| U+000AE | ® |
reg
| U+000AE | ® |
ReverseElement;
| U+0220B | ∋ |
ReverseEquilibrium;
| U+021CB | ⇋ |
ReverseUpEquilibrium;
| U+0296F | ⥯ |
rfisht;
| U+0297D | ⥽ |
rfloor;
| U+0230B | ⌋ |
Rfr;
| U+0211C | ℜ |
rfr;
| U+1D52F | 𝔯 |
rHar;
| U+02964 | ⥤ |
rhard;
| U+021C1 | ⇁ |
rharu;
| U+021C0 | ⇀ |
rharul;
| U+0296C | ⥬ |
Rho;
| U+003A1 | Ρ |
rho;
| U+003C1 | ρ |
rhov;
| U+003F1 | ϱ |
RightAngleBracket;
| U+027E9 | ⟩ |
RightArrow;
| U+02192 | → |
Rightarrow;
| U+021D2 | ⇒ |
rightarrow;
| U+02192 | → |
RightArrowBar;
| U+021E5 | ⇥ |
RightArrowLeftArrow;
| U+021C4 | ⇄ |
rightarrowtail;
| U+021A3 | ↣ |
RightCeiling;
| U+02309 | ⌉ |
RightDoubleBracket;
| U+027E7 | ⟧ |
RightDownTeeVector;
| U+0295D | ⥝ |
RightDownVector;
| U+021C2 | ⇂ |
RightDownVectorBar;
| U+02955 | ⥕ |
RightFloor;
| U+0230B | ⌋ |
rightharpoondown;
| U+021C1 | ⇁ |
rightharpoonup;
| U+021C0 | ⇀ |
rightleftarrows;
| U+021C4 | ⇄ |
rightleftharpoons;
| U+021CC | ⇌ |
rightrightarrows;
| U+021C9 | ⇉ |
rightsquigarrow;
| U+0219D | ↝ |
RightTee;
| U+022A2 | ⊢ |
RightTeeArrow;
| U+021A6 | ↦ |
RightTeeVector;
| U+0295B | ⥛ |
rightthreetimes;
| U+022CC | ⋌ |
RightTriangle;
| U+022B3 | ⊳ |
RightTriangleBar;
| U+029D0 | ⧐ |
RightTriangleEqual;
| U+022B5 | ⊵ |
RightUpDownVector;
| U+0294F | ⥏ |
RightUpTeeVector;
| U+0295C | ⥜ |
RightUpVector;
| U+021BE | ↾ |
RightUpVectorBar;
| U+02954 | ⥔ |
RightVector;
| U+021C0 | ⇀ |
RightVectorBar;
| U+02953 | ⥓ |
ring;
| U+002DA | ˚ |
risingdotseq;
| U+02253 | ≓ |
rlarr;
| U+021C4 | ⇄ |
rlhar;
| U+021CC | ⇌ |
rlm;
| U+0200F | |
rmoust;
| U+023B1 | ⎱ |
rmoustache;
| U+023B1 | ⎱ |
rnmid;
| U+02AEE | ⫮ |
roang;
| U+027ED | ⟭ |
roarr;
| U+021FE | ⇾ |
robrk;
| U+027E7 | ⟧ |
ropar;
| U+02986 | ⦆ |
Ropf;
| U+0211D | ℝ |
ropf;
| U+1D563 | 𝕣 |
roplus;
| U+02A2E | ⨮ |
rotimes;
| U+02A35 | ⨵ |
RoundImplies;
| U+02970 | ⥰ |
rpar;
| U+00029 | ) |
rpargt;
| U+02994 | ⦔ |
rppolint;
| U+02A12 | ⨒ |
rrarr;
| U+021C9 | ⇉ |
Rrightarrow;
| U+021DB | ⇛ |
rsaquo;
| U+0203A | › |
Rscr;
| U+0211B | ℛ |
rscr;
| U+1D4C7 | 𝓇 |
Rsh;
| U+021B1 | ↱ |
rsh;
| U+021B1 | ↱ |
rsqb;
| U+0005D | ] |
rsquo;
| U+02019 | ’ |
rsquor;
| U+02019 | ’ |
rthree;
| U+022CC | ⋌ |
rtimes;
| U+022CA | ⋊ |
rtri;
| U+025B9 | ▹ |
rtrie;
| U+022B5 | ⊵ |
rtrif;
| U+025B8 | ▸ |
rtriltri;
| U+029CE | ⧎ |
RuleDelayed;
| U+029F4 | ⧴ |
ruluhar;
| U+02968 | ⥨ |
rx;
| U+0211E | ℞ |
Sacute;
| U+0015A | Ś |
sacute;
| U+0015B | ś |
sbquo;
| U+0201A | ‚ |
Sc;
| U+02ABC | ⪼ |
sc;
| U+0227B | ≻ |
scap;
| U+02AB8 | ⪸ |
Scaron;
| U+00160 | Š |
scaron;
| U+00161 | š |
sccue;
| U+0227D | ≽ |
scE;
| U+02AB4 | ⪴ |
sce;
| U+02AB0 | ⪰ |
Scedil;
| U+0015E | Ş |
scedil;
| U+0015F | ş |
Scirc;
| U+0015C | Ŝ |
scirc;
| U+0015D | ŝ |
scnap;
| U+02ABA | ⪺ |
scnE;
| U+02AB6 | ⪶ |
scnsim;
| U+022E9 | ⋩ |
scpolint;
| U+02A13 | ⨓ |
scsim;
| U+0227F | ≿ |
Scy;
| U+00421 | С |
scy;
| U+00441 | с |
sdot;
| U+022C5 | ⋅ |
sdotb;
| U+022A1 | ⊡ |
sdote;
| U+02A66 | ⩦ |
searhk;
| U+02925 | ⤥ |
seArr;
| U+021D8 | ⇘ |
searr;
| U+02198 | ↘ |
searrow;
| U+02198 | ↘ |
sect;
| U+000A7 | § |
sect
| U+000A7 | § |
semi;
| U+0003B | ; |
seswar;
| U+02929 | ⤩ |
setminus;
| U+02216 | ∖ |
setmn;
| U+02216 | ∖ |
sext;
| U+02736 | ✶ |
Sfr;
| U+1D516 | 𝔖 |
sfr;
| U+1D530 | 𝔰 |
sfrown;
| U+02322 | ⌢ |
sharp;
| U+0266F | ♯ |
SHCHcy;
| U+00429 | Щ |
shchcy;
| U+00449 | щ |
SHcy;
| U+00428 | Ш |
shcy;
| U+00448 | ш |
ShortDownArrow;
| U+02193 | ↓ |
ShortLeftArrow;
| U+02190 | ← |
shortmid;
| U+02223 | ∣ |
shortparallel;
| U+02225 | ∥ |
ShortRightArrow;
| U+02192 | → |
ShortUpArrow;
| U+02191 | ↑ |
shy;
| U+000AD | |
shy
| U+000AD | |
Sigma;
| U+003A3 | Σ |
sigma;
| U+003C3 | σ |
sigmaf;
| U+003C2 | ς |
sigmav;
| U+003C2 | ς |
sim;
| U+0223C | ∼ |
simdot;
| U+02A6A | ⩪ |
sime;
| U+02243 | ≃ |
simeq;
| U+02243 | ≃ |
simg;
| U+02A9E | ⪞ |
simgE;
| U+02AA0 | ⪠ |
siml;
| U+02A9D | ⪝ |
simlE;
| U+02A9F | ⪟ |
simne;
| U+02246 | ≆ |
simplus;
| U+02A24 | ⨤ |
simrarr;
| U+02972 | ⥲ |
slarr;
| U+02190 | ← |
SmallCircle;
| U+02218 | ∘ |
smallsetminus;
| U+02216 | ∖ |
smashp;
| U+02A33 | ⨳ |
smeparsl;
| U+029E4 | ⧤ |
smid;
| U+02223 | ∣ |
smile;
| U+02323 | ⌣ |
smt;
| U+02AAA | ⪪ |
smte;
| U+02AAC | ⪬ |
smtes;
| U+02AAC U+0FE00 | ⪬︀ |
SOFTcy;
| U+0042C | Ь |
softcy;
| U+0044C | ь |
sol;
| U+0002F | / |
solb;
| U+029C4 | ⧄ |
solbar;
| U+0233F | ⌿ |
Sopf;
| U+1D54A | 𝕊 |
sopf;
| U+1D564 | 𝕤 |
spades;
| U+02660 | ♠ |
spadesuit;
| U+02660 | ♠ |
spar;
| U+02225 | ∥ |
sqcap;
| U+02293 | ⊓ |
sqcaps;
| U+02293 U+0FE00 | ⊓︀ |
sqcup;
| U+02294 | ⊔ |
sqcups;
| U+02294 U+0FE00 | ⊔︀ |
Sqrt;
| U+0221A | √ |
sqsub;
| U+0228F | ⊏ |
sqsube;
| U+02291 | ⊑ |
sqsubset;
| U+0228F | ⊏ |
sqsubseteq;
| U+02291 | ⊑ |
sqsup;
| U+02290 | ⊐ |
sqsupe;
| U+02292 | ⊒ |
sqsupset;
| U+02290 | ⊐ |
sqsupseteq;
| U+02292 | ⊒ |
squ;
| U+025A1 | □ |
Square;
| U+025A1 | □ |
square;
| U+025A1 | □ |
SquareIntersection;
| U+02293 | ⊓ |
SquareSubset;
| U+0228F | ⊏ |
SquareSubsetEqual;
| U+02291 | ⊑ |
SquareSuperset;
| U+02290 | ⊐ |
SquareSupersetEqual;
| U+02292 | ⊒ |
SquareUnion;
| U+02294 | ⊔ |
squarf;
| U+025AA | ▪ |
squf;
| U+025AA | ▪ |
srarr;
| U+02192 | → |
Sscr;
| U+1D4AE | 𝒮 |
sscr;
| U+1D4C8 | 𝓈 |
ssetmn;
| U+02216 | ∖ |
ssmile;
| U+02323 | ⌣ |
sstarf;
| U+022C6 | ⋆ |
Star;
| U+022C6 | ⋆ |
star;
| U+02606 | ☆ |
starf;
| U+02605 | ★ |
straightepsilon;
| U+003F5 | ϵ |
straightphi;
| U+003D5 | ϕ |
strns;
| U+000AF | ¯ |
Sub;
| U+022D0 | ⋐ |
sub;
| U+02282 | ⊂ |
subdot;
| U+02ABD | ⪽ |
subE;
| U+02AC5 | ⫅ |
sube;
| U+02286 | ⊆ |
subedot;
| U+02AC3 | ⫃ |
submult;
| U+02AC1 | ⫁ |
subnE;
| U+02ACB | ⫋ |
subne;
| U+0228A | ⊊ |
subplus;
| U+02ABF | ⪿ |
subrarr;
| U+02979 | ⥹ |
Subset;
| U+022D0 | ⋐ |
subset;
| U+02282 | ⊂ |
subseteq;
| U+02286 | ⊆ |
subseteqq;
| U+02AC5 | ⫅ |
SubsetEqual;
| U+02286 | ⊆ |
subsetneq;
| U+0228A | ⊊ |
subsetneqq;
| U+02ACB | ⫋ |
subsim;
| U+02AC7 | ⫇ |
subsub;
| U+02AD5 | ⫕ |
subsup;
| U+02AD3 | ⫓ |
succ;
| U+0227B | ≻ |
succapprox;
| U+02AB8 | ⪸ |
succcurlyeq;
| U+0227D | ≽ |
Succeeds;
| U+0227B | ≻ |
SucceedsEqual;
| U+02AB0 | ⪰ |
SucceedsSlantEqual;
| U+0227D | ≽ |
SucceedsTilde;
| U+0227F | ≿ |
succeq;
| U+02AB0 | ⪰ |
succnapprox;
| U+02ABA | ⪺ |
succneqq;
| U+02AB6 | ⪶ |
succnsim;
| U+022E9 | ⋩ |
succsim;
| U+0227F | ≿ |
SuchThat;
| U+0220B | ∋ |
Sum;
| U+02211 | ∑ |
sum;
| U+02211 | ∑ |
sung;
| U+0266A | ♪ |
Sup;
| U+022D1 | ⋑ |
sup;
| U+02283 | ⊃ |
sup1;
| U+000B9 | ¹ |
sup1
| U+000B9 | ¹ |
sup2;
| U+000B2 | ² |
sup2
| U+000B2 | ² |
sup3;
| U+000B3 | ³ |
sup3
| U+000B3 | ³ |
supdot;
| U+02ABE | ⪾ |
supdsub;
| U+02AD8 | ⫘ |
supE;
| U+02AC6 | ⫆ |
supe;
| U+02287 | ⊇ |
supedot;
| U+02AC4 | ⫄ |
Superset;
| U+02283 | ⊃ |
SupersetEqual;
| U+02287 | ⊇ |
suphsol;
| U+027C9 | ⟉ |
suphsub;
| U+02AD7 | ⫗ |
suplarr;
| U+0297B | ⥻ |
supmult;
| U+02AC2 | ⫂ |
supnE;
| U+02ACC | ⫌ |
supne;
| U+0228B | ⊋ |
supplus;
| U+02AC0 | ⫀ |
Supset;
| U+022D1 | ⋑ |
supset;
| U+02283 | ⊃ |
supseteq;
| U+02287 | ⊇ |
supseteqq;
| U+02AC6 | ⫆ |
supsetneq;
| U+0228B | ⊋ |
supsetneqq;
| U+02ACC | ⫌ |
supsim;
| U+02AC8 | ⫈ |
supsub;
| U+02AD4 | ⫔ |
supsup;
| U+02AD6 | ⫖ |
swarhk;
| U+02926 | ⤦ |
swArr;
| U+021D9 | ⇙ |
swarr;
| U+02199 | ↙ |
swarrow;
| U+02199 | ↙ |
swnwar;
| U+0292A | ⤪ |
szlig;
| U+000DF | ß |
szlig
| U+000DF | ß |
Tab;
| U+00009 | ␉ |
target;
| U+02316 | ⌖ |
Tau;
| U+003A4 | Τ |
tau;
| U+003C4 | τ |
tbrk;
| U+023B4 | ⎴ |
Tcaron;
| U+00164 | Ť |
tcaron;
| U+00165 | ť |
Tcedil;
| U+00162 | Ţ |
tcedil;
| U+00163 | ţ |
Tcy;
| U+00422 | Т |
tcy;
| U+00442 | т |
tdot;
| U+020DB | ◌⃛ |
telrec;
| U+02315 | ⌕ |
Tfr;
| U+1D517 | 𝔗 |
tfr;
| U+1D531 | 𝔱 |
there4;
| U+02234 | ∴ |
Therefore;
| U+02234 | ∴ |
therefore;
| U+02234 | ∴ |
Theta;
| U+00398 | Θ |
theta;
| U+003B8 | θ |
thetasym;
| U+003D1 | ϑ |
thetav;
| U+003D1 | ϑ |
thickapprox;
| U+02248 | ≈ |
thicksim;
| U+0223C | ∼ |
ThickSpace;
| U+0205F U+0200A | |
thinsp;
| U+02009 | |
ThinSpace;
| U+02009 | |
thkap;
| U+02248 | ≈ |
thksim;
| U+0223C | ∼ |
THORN;
| U+000DE | Þ |
THORN
| U+000DE | Þ |
thorn;
| U+000FE | þ |
thorn
| U+000FE | þ |
Tilde;
| U+0223C | ∼ |
tilde;
| U+002DC | ˜ |
TildeEqual;
| U+02243 | ≃ |
TildeFullEqual;
| U+02245 | ≅ |
TildeTilde;
| U+02248 | ≈ |
times;
| U+000D7 | × |
times
| U+000D7 | × |
timesb;
| U+022A0 | ⊠ |
timesbar;
| U+02A31 | ⨱ |
timesd;
| U+02A30 | ⨰ |
tint;
| U+0222D | ∭ |
toea;
| U+02928 | ⤨ |
top;
| U+022A4 | ⊤ |
topbot;
| U+02336 | ⌶ |
topcir;
| U+02AF1 | ⫱ |
Topf;
| U+1D54B | 𝕋 |
topf;
| U+1D565 | 𝕥 |
topfork;
| U+02ADA | ⫚ |
tosa;
| U+02929 | ⤩ |
tprime;
| U+02034 | ‴ |
TRADE;
| U+02122 | ™ |
trade;
| U+02122 | ™ |
triangle;
| U+025B5 | ▵ |
triangledown;
| U+025BF | ▿ |
triangleleft;
| U+025C3 | ◃ |
trianglelefteq;
| U+022B4 | ⊴ |
triangleq;
| U+0225C | ≜ |
triangleright;
| U+025B9 | ▹ |
trianglerighteq;
| U+022B5 | ⊵ |
tridot;
| U+025EC | ◬ |
trie;
| U+0225C | ≜ |
triminus;
| U+02A3A | ⨺ |
TripleDot;
| U+020DB | ◌⃛ |
triplus;
| U+02A39 | ⨹ |
trisb;
| U+029CD | ⧍ |
tritime;
| U+02A3B | ⨻ |
trpezium;
| U+023E2 | ⏢ |
Tscr;
| U+1D4AF | 𝒯 |
tscr;
| U+1D4C9 | 𝓉 |
TScy;
| U+00426 | Ц |
tscy;
| U+00446 | ц |
TSHcy;
| U+0040B | Ћ |
tshcy;
| U+0045B | ћ |
Tstrok;
| U+00166 | Ŧ |
tstrok;
| U+00167 | ŧ |
twixt;
| U+0226C | ≬ |
twoheadleftarrow;
| U+0219E | ↞ |
twoheadrightarrow;
| U+021A0 | ↠ |
Uacute;
| U+000DA | Ú |
Uacute
| U+000DA | Ú |
uacute;
| U+000FA | ú |
uacute
| U+000FA | ú |
Uarr;
| U+0219F | ↟ |
uArr;
| U+021D1 | ⇑ |
uarr;
| U+02191 | ↑ |
Uarrocir;
| U+02949 | ⥉ |
Ubrcy;
| U+0040E | Ў |
ubrcy;
| U+0045E | ў |
Ubreve;
| U+0016C | Ŭ |
ubreve;
| U+0016D | ŭ |
Ucirc;
| U+000DB | Û |
Ucirc
| U+000DB | Û |
ucirc;
| U+000FB | û |
ucirc
| U+000FB | û |
Ucy;
| U+00423 | У |
ucy;
| U+00443 | у |
udarr;
| U+021C5 | ⇅ |
Udblac;
| U+00170 | Ű |
udblac;
| U+00171 | ű |
udhar;
| U+0296E | ⥮ |
ufisht;
| U+0297E | ⥾ |
Ufr;
| U+1D518 | 𝔘 |
ufr;
| U+1D532 | 𝔲 |
Ugrave;
| U+000D9 | Ù |
Ugrave
| U+000D9 | Ù |
ugrave;
| U+000F9 | ù |
ugrave
| U+000F9 | ù |
uHar;
| U+02963 | ⥣ |
uharl;
| U+021BF | ↿ |
uharr;
| U+021BE | ↾ |
uhblk;
| U+02580 | ▀ |
ulcorn;
| U+0231C | ⌜ |
ulcorner;
| U+0231C | ⌜ |
ulcrop;
| U+0230F | ⌏ |
ultri;
| U+025F8 | ◸ |
Umacr;
| U+0016A | Ū |
umacr;
| U+0016B | ū |
uml;
| U+000A8 | ¨ |
uml
| U+000A8 | ¨ |
UnderBar;
| U+0005F | _ |
UnderBrace;
| U+023DF | ⏟ |
UnderBracket;
| U+023B5 | ⎵ |
UnderParenthesis;
| U+023DD | ⏝ |
Union;
| U+022C3 | ⋃ |
UnionPlus;
| U+0228E | ⊎ |
Uogon;
| U+00172 | Ų |
uogon;
| U+00173 | ų |
Uopf;
| U+1D54C | 𝕌 |
uopf;
| U+1D566 | 𝕦 |
UpArrow;
| U+02191 | ↑ |
Uparrow;
| U+021D1 | ⇑ |
uparrow;
| U+02191 | ↑ |
UpArrowBar;
| U+02912 | ⤒ |
UpArrowDownArrow;
| U+021C5 | ⇅ |
UpDownArrow;
| U+02195 | ↕ |
Updownarrow;
| U+021D5 | ⇕ |
updownarrow;
| U+02195 | ↕ |
UpEquilibrium;
| U+0296E | ⥮ |
upharpoonleft;
| U+021BF | ↿ |
upharpoonright;
| U+021BE | ↾ |
uplus;
| U+0228E | ⊎ |
UpperLeftArrow;
| U+02196 | ↖ |
UpperRightArrow;
| U+02197 | ↗ |
Upsi;
| U+003D2 | ϒ |
upsi;
| U+003C5 | υ |
upsih;
| U+003D2 | ϒ |
Upsilon;
| U+003A5 | Υ |
upsilon;
| U+003C5 | υ |
UpTee;
| U+022A5 | ⊥ |
UpTeeArrow;
| U+021A5 | ↥ |
upuparrows;
| U+021C8 | ⇈ |
urcorn;
| U+0231D | ⌝ |
urcorner;
| U+0231D | ⌝ |
urcrop;
| U+0230E | ⌎ |
Uring;
| U+0016E | Ů |
uring;
| U+0016F | ů |
urtri;
| U+025F9 | ◹ |
Uscr;
| U+1D4B0 | 𝒰 |
uscr;
| U+1D4CA | 𝓊 |
utdot;
| U+022F0 | ⋰ |
Utilde;
| U+00168 | Ũ |
utilde;
| U+00169 | ũ |
utri;
| U+025B5 | ▵ |
utrif;
| U+025B4 | ▴ |
uuarr;
| U+021C8 | ⇈ |
Uuml;
| U+000DC | Ü |
Uuml
| U+000DC | Ü |
uuml;
| U+000FC | ü |
uuml
| U+000FC | ü |
uwangle;
| U+029A7 | ⦧ |
vangrt;
| U+0299C | ⦜ |
varepsilon;
| U+003F5 | ϵ |
varkappa;
| U+003F0 | ϰ |
varnothing;
| U+02205 | ∅ |
varphi;
| U+003D5 | ϕ |
varpi;
| U+003D6 | ϖ |
varpropto;
| U+0221D | ∝ |
vArr;
| U+021D5 | ⇕ |
varr;
| U+02195 | ↕ |
varrho;
| U+003F1 | ϱ |
varsigma;
| U+003C2 | ς |
varsubsetneq;
| U+0228A U+0FE00 | ⊊︀ |
varsubsetneqq;
| U+02ACB U+0FE00 | ⫋︀ |
varsupsetneq;
| U+0228B U+0FE00 | ⊋︀ |
varsupsetneqq;
| U+02ACC U+0FE00 | ⫌︀ |
vartheta;
| U+003D1 | ϑ |
vartriangleleft;
| U+022B2 | ⊲ |
vartriangleright;
| U+022B3 | ⊳ |
Vbar;
| U+02AEB | ⫫ |
vBar;
| U+02AE8 | ⫨ |
vBarv;
| U+02AE9 | ⫩ |
Vcy;
| U+00412 | В |
vcy;
| U+00432 | в |
VDash;
| U+022AB | ⊫ |
Vdash;
| U+022A9 | ⊩ |
vDash;
| U+022A8 | ⊨ |
vdash;
| U+022A2 | ⊢ |
Vdashl;
| U+02AE6 | ⫦ |
Vee;
| U+022C1 | ⋁ |
vee;
| U+02228 | ∨ |
veebar;
| U+022BB | ⊻ |
veeeq;
| U+0225A | ≚ |
vellip;
| U+022EE | ⋮ |
Verbar;
| U+02016 | ‖ |
verbar;
| U+0007C | | |
Vert;
| U+02016 | ‖ |
vert;
| U+0007C | | |
VerticalBar;
| U+02223 | ∣ |
VerticalLine;
| U+0007C | | |
VerticalSeparator;
| U+02758 | ❘ |
VerticalTilde;
| U+02240 | ≀ |
VeryThinSpace;
| U+0200A | |
Vfr;
| U+1D519 | 𝔙 |
vfr;
| U+1D533 | 𝔳 |
vltri;
| U+022B2 | ⊲ |
vnsub;
| U+02282 U+020D2 | ⊂⃒ |
vnsup;
| U+02283 U+020D2 | ⊃⃒ |
Vopf;
| U+1D54D | 𝕍 |
vopf;
| U+1D567 | 𝕧 |
vprop;
| U+0221D | ∝ |
vrtri;
| U+022B3 | ⊳ |
Vscr;
| U+1D4B1 | 𝒱 |
vscr;
| U+1D4CB | 𝓋 |
vsubnE;
| U+02ACB U+0FE00 | ⫋︀ |
vsubne;
| U+0228A U+0FE00 | ⊊︀ |
vsupnE;
| U+02ACC U+0FE00 | ⫌︀ |
vsupne;
| U+0228B U+0FE00 | ⊋︀ |
Vvdash;
| U+022AA | ⊪ |
vzigzag;
| U+0299A | ⦚ |
Wcirc;
| U+00174 | Ŵ |
wcirc;
| U+00175 | ŵ |
wedbar;
| U+02A5F | ⩟ |
Wedge;
| U+022C0 | ⋀ |
wedge;
| U+02227 | ∧ |
wedgeq;
| U+02259 | ≙ |
weierp;
| U+02118 | ℘ |
Wfr;
| U+1D51A | 𝔚 |
wfr;
| U+1D534 | 𝔴 |
Wopf;
| U+1D54E | 𝕎 |
wopf;
| U+1D568 | 𝕨 |
wp;
| U+02118 | ℘ |
wr;
| U+02240 | ≀ |
wreath;
| U+02240 | ≀ |
Wscr;
| U+1D4B2 | 𝒲 |
wscr;
| U+1D4CC | 𝓌 |
xcap;
| U+022C2 | ⋂ |
xcirc;
| U+025EF | ◯ |
xcup;
| U+022C3 | ⋃ |
xdtri;
| U+025BD | ▽ |
Xfr;
| U+1D51B | 𝔛 |
xfr;
| U+1D535 | 𝔵 |
xhArr;
| U+027FA | ⟺ |
xharr;
| U+027F7 | ⟷ |
Xi;
| U+0039E | Ξ |
xi;
| U+003BE | ξ |
xlArr;
| U+027F8 | ⟸ |
xlarr;
| U+027F5 | ⟵ |
xmap;
| U+027FC | ⟼ |
xnis;
| U+022FB | ⋻ |
xodot;
| U+02A00 | ⨀ |
Xopf;
| U+1D54F | 𝕏 |
xopf;
| U+1D569 | 𝕩 |
xoplus;
| U+02A01 | ⨁ |
xotime;
| U+02A02 | ⨂ |
xrArr;
| U+027F9 | ⟹ |
xrarr;
| U+027F6 | ⟶ |
Xscr;
| U+1D4B3 | 𝒳 |
xscr;
| U+1D4CD | 𝓍 |
xsqcup;
| U+02A06 | ⨆ |
xuplus;
| U+02A04 | ⨄ |
xutri;
| U+025B3 | △ |
xvee;
| U+022C1 | ⋁ |
xwedge;
| U+022C0 | ⋀ |
Yacute;
| U+000DD | Ý |
Yacute
| U+000DD | Ý |
yacute;
| U+000FD | ý |
yacute
| U+000FD | ý |
YAcy;
| U+0042F | Я |
yacy;
| U+0044F | я |
Ycirc;
| U+00176 | Ŷ |
ycirc;
| U+00177 | ŷ |
Ycy;
| U+0042B | Ы |
ycy;
| U+0044B | ы |
yen;
| U+000A5 | ¥ |
yen
| U+000A5 | ¥ |
Yfr;
| U+1D51C | 𝔜 |
yfr;
| U+1D536 | 𝔶 |
YIcy;
| U+00407 | Ї |
yicy;
| U+00457 | ї |
Yopf;
| U+1D550 | 𝕐 |
yopf;
| U+1D56A | 𝕪 |
Yscr;
| U+1D4B4 | 𝒴 |
yscr;
| U+1D4CE | 𝓎 |
YUcy;
| U+0042E | Ю |
yucy;
| U+0044E | ю |
Yuml;
| U+00178 | Ÿ |
yuml;
| U+000FF | ÿ |
yuml
| U+000FF | ÿ |
Zacute;
| U+00179 | Ź |
zacute;
| U+0017A | ź |
Zcaron;
| U+0017D | Ž |
zcaron;
| U+0017E | ž |
Zcy;
| U+00417 | З |
zcy;
| U+00437 | з |
Zdot;
| U+0017B | Ż |
zdot;
| U+0017C | ż |
zeetrf;
| U+02128 | ℨ |
ZeroWidthSpace;
| U+0200B | |
Zeta;
| U+00396 | Ζ |
zeta;
| U+003B6 | ζ |
Zfr;
| U+02128 | ℨ |
zfr;
| U+1D537 | 𝔷 |
ZHcy;
| U+00416 | Ж |
zhcy;
| U+00436 | ж |
zigrarr;
| U+021DD | ⇝ |
Zopf;
| U+02124 | ℤ |
zopf;
| U+1D56B | 𝕫 |
Zscr;
| U+1D4B5 | 𝒵 |
zscr;
| U+1D4CF | 𝓏 |
zwj;
| U+0200D | |
zwnj;
| U+0200C | |
This data is also available as a JSON file.
The glyphs displayed above are non-normative. Refer to Unicode for formal definitions of the characters listed above.
The character reference names originate from XML Entity Definitions for Characters, though only the above is considered normative. [XMLENTITY]
This list is static and will not be expanded or changed in the future.
Support in all current engines.
This section only describes the rules for XML resources. Rules for
text/html resources are
discussed in
the
section above entitled "The HTML
syntax".
Using the XML syntax is not recommended, for
reasons which include the fact that there is no specification which defines the rules for how an
XML parser must map a string of bytes or characters into a Document object, as well
as the fact that the XML syntax is essentially unmaintained — in that, it’s not expected that
any
further features will ever be added to the XML syntax (even when such features have been added
to
the HTML syntax).
The XML syntax for HTML was formerly referred to as "XHTML", but this specification does not use that term (among other reasons, because no such term is used for the HTML syntaxes of MathML and SVG).
The syntax for XML is defined in XML and Namespaces in XML. [XML] [XMLNS]
This specification does not define any syntax-level requirements beyond those defined for XML proper.
XML documents may contain a DOCTYPE if desired, but this is not required
to conform to this specification. This specification does not define a public or system
identifier, nor provide a formal DTD.
According to XML, XML processors are not guaranteed to process
the external DTD subset referenced in the DOCTYPE. This means, for example, that using entity references for characters in XML
documents
is unsafe if they are defined in an external file (except for <,
>, &,
", and ').
This section describes the relationship between XML and the DOM, with a particular emphasis on how this interacts with HTML.
An XML parser, for the purposes of this specification, is
a
construct
that
follows the rules given in XML to map a string of bytes or characters into a
Document object.
At the time of writing, no such rules actually exist.
An XML parser is either associated
with a
Document object when it
is
created, or creates one implicitly.
This Document must then
be
populated
with DOM nodes that represent the tree
structure of the input passed to the parser, as defined by XML, Namespaces
in XML, and DOM. When creating DOM nodes representing elements,
the create
an element for a token algorithm
or some equivalent that operates on appropriate XML data structures must be used, to ensure the
proper element
interfaces are
created and that custom
elements
are set
up correctly.
DOM mutation events must not fire for the operations that the XML parser performs
on the Document's tree,
but the
user
agent must act as if elements and attributes
were individually appended and set respectively so as to trigger rules in this specification
regarding what happens when an element is inserted into a document or has its attributes set,
and
DOM's requirements regarding mutation
observers mean that
mutation observers are fired (unlike mutation events). [XML] [XMLNS]
[DOM] [UIEVENTS]
Between the time an element's start tag is parsed and the time either the element's end tag is parsed or the parser detects a well-formedness error, the user agent must act as if the element was in a stack of open elements.
This is used by various elements to only start certain processes once they are popped off of the stack of open elements.
This specification provides the following additional information that user agents should use when retrieving an external entity: the public identifiers given in the following list all correspond to the URL given by this link. (This URL is a DTD containing the entity declarations for the names listed in the named character references section.) [XML]
-//W3C//DTD XHTML 1.0 Transitional//EN
-//W3C//DTD XHTML 1.1//EN
-//W3C//DTD XHTML 1.0 Strict//EN
-//W3C//DTD XHTML 1.0 Frameset//EN
-//W3C//DTD XHTML Basic 1.0//EN
-//W3C//DTD XHTML 1.1 plus MathML 2.0//EN
-//W3C//DTD XHTML 1.1 plus MathML 2.0 plus SVG 1.1//EN
-//W3C//DTD MathML 2.0//EN
-//WAPFORUM//DTD XHTML Mobile 1.0//EN
Furthermore, user agents should attempt to retrieve the above external entity's content when one of the above public identifiers is used, and should not attempt to retrieve any other external entity's content.
This is not strictly a violation of XML, but it does contradict the spirit of XML's requirements. This is motivated by a desire for user agents to all handle entities in an interoperable fashion without requiring any network access for handling external subsets. [XML]
XML parsers can be invoked with XML scripting support enabled or XML scripting support disabled. Except where otherwise specified, XML parsers are invoked with XML scripting support enabled.
When an XML
parser with
XML
scripting
support
enabled creates a script
element,
it must
have its parser
document set and its force
async set to false. If
the parser was created as part of the XML fragment parsing
algorithm, then
the
element's already
started must
be set to
true. When the element's end tag is
subsequently parsed, the user agent must perform a microtask
checkpoint, and
then
prepare
the script
element. If
this
causes there to be a pending parsing-blocking
script, then
the
user agent must run
the following steps:
Block this instance of the XML parser, such that the event loop will not run tasks that invoke it.
Spin the
event
loop until
the parser's Document
has no
style sheet that is blocking scripts and the pending
parsing-blocking
script's ready to be
parser-executed is
true.
Unblock this instance of the XML parser, such that tasks that invoke it can again be run.
Execute the script element given by the pending parsing-blocking script.
Set the pending parsing-blocking script to null.
Since the document.write()
API is
not
available for XML
documents, much of the complexity in the HTML parser
is not needed in the XML parser.
When the XML parser has XML scripting support disabled, none of this happens.
When an XML
parser
would append
a node to a
template
element,
it must instead append it to the template
element's
template contents (a
DocumentFragment
node).
This is a willful
violation of XML; unfortunately,
XML is not formally extensible in the manner that is needed for template
processing.
[XML]
When an XML parser creates a
Node
object, its node
document
must be set to the node
document of
the node into which the newly created node is to be inserted.
Certain algorithms in this specification spoon-feed the parser characters one string at a time. In such cases, the XML parser must act as it would have if faced with a single string consisting of the concatenation of all those characters.
When an XML parser reaches the end of its input, it must stop parsing, following the same rules as the HTML parser. An XML parser can also be aborted, which must again be done in the same way as for an HTML parser.
For the purposes of conformance checkers, if a resource is determined to be in the XML syntax, then it is an XML document.
The XML fragment serialization
algorithm for a Document or
Element
node either returns a fragment
of XML that represents that node or throws an exception.
For Documents, the
algorithm
must
return a string in the form of a document
entity,
if none
of the error cases
below apply.
For Elements,
the algorithm must return a string in the form of an internal
general parsed entity, if none of the
error cases below apply.
In both cases, the string returned must be XML namespace-well-formed and must be an isomorphic
serialization of all of that node's relevant child nodes, in tree
order.
User agents may adjust prefixes and namespace declarations in the serialization (and indeed
might
be forced to do so in some cases to obtain namespace-well-formed XML). User agents may use a
combination of regular text and character references to represent Text
nodes in the
DOM.
A node's relevant child nodes are those that apply given the following rules:
template
elements
template
element's template
contents,
if any.
For Elements,
if any of the elements in the serialization are in no namespace, the
default namespace in scope for those elements must be explicitly declared as the empty string.
(This
doesn't
apply in the Document
case.) [XML]
[XMLNS]
For the purposes of this section, an internal general parsed entity is considered XML namespace-well-formed if a document consisting of an element with no namespace declarations whose contents are the internal general parsed entity would itself be XML namespace-well-formed.
If any of the following error cases are found in the DOM subtree being serialized, then the
algorithm must throw an "InvalidStateError" DOMException
instead of returning a string:
Document node
with no
child
element nodes.
DocumentType
node that has an external subset public identifier that contains
characters that are not matched by the XML PubidChar production. [XML]
DocumentType
node that has an external subset system identifier that contains
both a U+0022 QUOTATION MARK (") and a U+0027 APOSTROPHE (') or that contains characters
that are
not matched by the XML Char production. [XML]
Name
production. [XML]
Attr
node with no namespace whose local name is the lowercase string "xmlns". [XMLNS]
Element
node with two or more attributes with the same local name and
namespace.
Attr
node, Text
node, Comment
node, or
ProcessingInstruction
node whose data contains characters that are not matched by
the XML Char production. [XML]
Comment
node whose data contains two adjacent U+002D HYPHEN-MINUS characters
(-) or ends with such a character.
ProcessingInstruction
node whose target name is an ASCII
case-insensitive match for the string "xml".
ProcessingInstruction
node whose target name contains a U+003A COLON (:).
ProcessingInstruction
node whose data contains the string "?>".
These are the only ways to make a DOM unserialisable. The DOM enforces all the
other XML constraints; for example, trying to append two elements to a Document node
will throw a "HierarchyRequestError" DOMException.
The XML fragment parsing algorithm either returns a
Document or throws
a "SyntaxError" DOMException.
Given a string
input and a context element context, the
algorithm is as follows:
Create a new XML parser.
Feed the parser just created the string corresponding to the start tag of the context element, declaring all the namespace prefixes that are in scope on that element in the DOM, as well as declaring the default namespace (if any) that is in scope on that element in the DOM.
A namespace prefix is in scope if the DOM lookupNamespaceURI() method
on the element would return a non-null value for that prefix.
The default namespace is the namespace for which the DOM
isDefaultNamespace() method
on the
element would return true.
No
DOCTYPE is passed to the parser, and therefore no external subset is
referenced, and therefore no entities will be recognized.
Feed the parser just created the string input.
Feed the parser just created the string corresponding to the end tag of the context element.
If there is an XML well-formedness or XML namespace well-formedness error, then throw a
"SyntaxError" DOMException.
If the document
element of the resulting Document has any
sibling
nodes, then throw a "SyntaxError" DOMException.
Return the child nodes of the document
element of the resulting
Document, in tree
order.
User agents are not required to present HTML documents in any particular way. However, this section provides a set of suggestions for rendering HTML documents that, if followed, are likely to lead to a user experience that closely resembles the experience intended by the documents' authors. So as to avoid confusion regarding the normativity of this section, "must" has not been used. Instead, the term "expected" is used to indicate behavior that will lead to this experience. For the purposes of conformance for user agents designated as supporting the suggested default rendering, the term "expected" in this section has the same conformance implications as "must".
The suggestions in this section are generally expressed in CSS terms. User agents are expected to either support CSS, or translate from the CSS rules given in this section to approximations for other presentation mechanisms.
In the absence of style-layer rules to the contrary (e.g. author style sheets), user agents are expected to render an element so that it conveys to the user the meaning that the element represents, as described by this specification.
The suggestions in this section generally assume a visual output medium with a resolution of 96dpi or greater, but HTML is intended to apply to multiple media (it is a media-independent language). User agent implementers are encouraged to adapt the suggestions in this section to their target media.
An element is being rendered if it has any associated CSS layout boxes, SVG layout boxes, or some equivalent in other styling languages.
Just being off-screen does not mean the element is not being rendered. The presence of the attribute normally means the element is not being rendered, though this might be overridden by the style sheets.
The fully active state does not affect whether an element is being rendered or not. Even if a document is not fully active and not shown at all to the user, elements within it can still qualify as "being rendered".
An element is said to intersect the viewport when it is being rendered and its associated CSS layout box intersects the viewport.
Similar to the being rendered state, elements in non-fully active documents can still intersect the viewport. The viewport is not shared between documents and might not always be shown to the user, so an element in a non-fully active document can still intersect the viewport associated with its document.
This specification does not define the precise timing for when the intersection is tested, but it is suggested that the timing match that of the Intersection Observer API. [INTERSECTIONOBSERVER]
An element is delegating its rendering to its children if it is not being rendered but its children (if any) could be rendered, as a result of CSS 'display: contents', or some equivalent in other styling languages. [CSSDISPLAY]
User agents that do not honor author-level CSS style sheets are nonetheless expected to act as if they applied the CSS rules given in these sections in a manner consistent with this specification and the relevant CSS and Unicode specifications. [CSS] [UNICODE] [BIDI]
This is especially important for issues relating to the 'display', 'unicode-bidi', and 'direction' properties.
The CSS rules given in these subsections are, except where otherwise specified, expected to be used as part of the user-agent level style sheet defaults for all documents that contain HTML elements.
Some rules are intended for the author-level zero-specificity presentational hints part of the CSS cascade; these are explicitly called out as presentational hints.
When the text below says that an attribute attribute on an element element maps to the pixel length property (or properties) properties, it means that if element has an attribute attribute set, and parsing that attribute's value using the rules for parsing non-negative integers doesn't generate an error, then the user agent is expected to use the parsed value as a pixel length for a presentational hint for properties.
When the text below says that an attribute attribute on an element element maps to the dimension property (or properties) properties, it means that if element has an attribute attribute set, and parsing that attribute's value using the rules for parsing dimension values doesn't generate an error, then the user agent is expected to use the parsed dimension as the value for a presentational hint for properties, with the value given as a pixel length if the dimension was a length, and with the value given as a percentage if the dimension was a percentage.
When the text below says that an attribute attribute on an element element maps to the dimension property (ignoring zero) (or properties) properties, it means that if element has an attribute attribute set, and parsing that attribute's value using the rules for parsing nonzero dimension values doesn't generate an error, then the user agent is expected to use the parsed dimension as the value for a presentational hint for properties, with the value given as a pixel length if the dimension was a length, and with the value given as a percentage if the dimension was a percentage.
When the text below says that a pair of attributes w and h on an
element element map to the aspect-ratio
property, it
means that if
element has both attributes w and h, and parsing those
attributes' values using the rules
for parsing non-negative integers doesn't
generate an error for either, then the user agent is expected to use the parsed integers as a
presentational
hint
for the 'aspect-ratio'
property of the form auto w / h.
When the text below says that a pair of attributes w and h on an
element element map
to the
aspect-ratio property (using dimension rules), it
means that if element has both attributes w and h, and parsing
those attributes' values using the rules
for
parsing dimension values doesn't
generate an error or return a percentage for either, then the user agent is expected to use the
parsed dimensions as a presentational
hint
for the
'aspect-ratio'
property of the form auto
w / h.
When a user agent is to align descendants of a node, the user
agent is
expected
to
align only those descendants that have both their 'margin-inline-start' and
'margin-inline-end' properties computing to a
value other
than
'auto', that are
over-constrained and that have one of those two margins with a used
value
forced to a
greater value, and that do not themselves have an applicable align
attribute. When multiple elements are to align a
particular descendant, the most deeply nested such element is expected to override the others.
Aligned elements are expected to be aligned by having the used
values of their margins on the line-left
and line-right
sides
be
set accordingly. [CSSLOGICAL] [CSSWM]
@namespace "http://www.w3.org/1999/xhtml" ;
area, base, basefont, datalist, head, link, meta, noembed,
noframes, param, rp, script, style, template, title {
display : none;
}
{
display : none;
}
[hidden=until-found i]:not(embed) {
content-visibility : hidden;
}
embed[hidden] { display : inline; height : 0 ; width : 0 ; }
input[type=hidden i] { display : none !important; }
@media (scripting) {
noscript { display: none !important; }
}
@namespace "http://www.w3.org/1999/xhtml" ;
html, body { display : block; }
For each property in the table below, given a body element, the first
attribute
that exists maps to
the
pixel length property on the body element. If
none of the attributes for a property are found, or if the value of the attribute that was found
cannot be parsed successfully, then a default value of 8px is expected to be used for that
property instead.
| Property | Source |
|---|---|
| 'margin-top' | The body
element's
marginheight
attribute
|
The body
element's
topmargin
attribute
| |
The body
element's
container frame
element's
marginheight
attribute
| |
| 'margin-right' | The body
element's
marginwidth
attribute
|
The body
element's
rightmargin
attribute
| |
The body
element's
container
frame
element's marginwidth
attribute
| |
| 'margin-bottom' | The body
element's
marginheight
attribute
|
The body
element's bottommargin
attribute
| |
The body
element's container
frame
element's marginheight
attribute
| |
| 'margin-left' | The body
element's marginwidth
attribute
|
The body
element's leftmargin
attribute
| |
The body
element's container
frame
element's marginwidth
attribute
|
If the body element's
node document's node
navigable is
a child navigable, and the container of that
navigable is a frame or iframe element, then
the
container frame element of the body element is that
frame or
iframe element.
Otherwise,
there
is no container frame
element.
The above requirements imply that a page can change the margins of another page
(including one from another origin)
using, for
example,
an iframe. This
is potentially a security risk, as it might in some cases allow an attack to contrive a
situation
in which a page is rendered not as the author intended, possibly for the purposes of phishing or
otherwise misleading the user.
If a Document's node navigable is a child navigable,
then it is expected to be positioned and sized to fit inside the content
box of
the
container of that navigable. If the container is not being
rendered, the
navigable is expected to have a viewport with zero width
and zero
height.
If a Document's node navigable is a child navigable,
the container of that navigable is a
frame or iframe element, that
element
has a
scrolling attribute, and that attribute's value is an ASCII
case-insensitive match for the string "off", "noscroll", or
"no",
then the user agent is expected to
prevent any scrollbars from being shown for the viewport of the
Document's node navigable, regardless of the 'overflow'
property that applies to that viewport.
When a body element
has a
background
attribute set to a non-empty value, the new value is expected to be encoding-parsed-and-serialized
relative to
the element's node
document, and if that does not return failure, the user agent
is
expected to treat the attribute as a presentational
hint setting the element's 'background-image' property to the return
value.
When a body element
has a
bgcolor
attribute set, the new value is expected to be parsed using the rules
for parsing a legacy
color value, and if that does not return an error, the user agent is expected to treat
the
attribute as a presentational
hint
setting
the
element's 'background-color' property to the resulting color.
When a body element
has a
text attribute, its
value is expected to be parsed using the rules for parsing a legacy color
value,
and
if that does not return an error, the user agent is expected to treat the attribute as a presentational hint
setting the
element's
'color' property to the resulting color.
When a body element
has a
link attribute, its
value is expected to be parsed using the rules for parsing a legacy color
value,
and
if that does not return an error, the user agent is expected to treat the attribute as a presentational hint
setting the 'color' property
of any element in the Document
matching the
:link
pseudo-class to the resulting color.
When a body element
has a
vlink attribute,
its value is expected to be parsed using the rules for parsing a legacy color
value,
and if that does not return an error, the user agent is expected to treat the attribute as a presentational hint
setting the 'color' property
of any element in the Document
matching the
:visited pseudo-class to the
resulting color.
When a body element
has an
alink attribute,
its value is expected to be parsed using the rules for parsing a legacy color
value,
and if that does not return an error, the user agent is expected to treat the attribute as a presentational hint
setting the 'color' property
of any element in the Document
matching the
:active pseudo-class and
either the :link pseudo-class or the :visited pseudo-class to the
resulting color.
@namespace "http://www.w3.org/1999/xhtml" ;
address, blockquote, center, dialog, div, figure, figcaption, footer, form,
header, hr, legend, listing, main, p, plaintext, pre, search, xmp {
display : block;
}
blockquote, figure, listing, p, plaintext, pre, xmp {
margin-block : 1 em ;
}
blockquote, figure { margin-inline : 40 px ; }
address { font-style : italic; }
listing, plaintext, pre, xmp {
font-family : monospace; white-space : pre;
}
dialog:not([open]) { display : none; }
dialog {
position : absolute;
inset-inline-start : 0 ; inset-inline-end : 0 ;
width : fit-content;
height : fit-content;
margin : auto;
border : solid;
padding : 1 em ;
background-color : Canvas;
color : CanvasText;
}
dialog:modal {
position : fixed;
overflow : auto;
inset-block : 0 ;
max-width : calc ( 100 % - 6 px - 2 em );
max-height : calc ( 100 % - 6 px - 2 em );
}
dialog::backdrop {
background : rgba ( 0 , 0 , 0 , 0.1 );
}
[popover]:not(:popover-open):not(dialog[open]) {
display : none;
}
dialog:popover-open {
display : block;
}
[popover] {
position : fixed;
inset : 0 ;
width : fit-content;
height : fit-content;
margin : auto;
border : solid;
padding : 0.25 em ;
overflow : auto;
color : CanvasText;
background-color : Canvas;
}
:popover-open::backdrop {
position : fixed;
inset : 0 ;
pointer-events : none !important;
background-color: transparent;
}
slot {
display: contents;
}
The following rules are also expected to apply, as presentational hints:
@namespace "http://www.w3.org/1999/xhtml" ;
pre[wrap] { white-space : pre-wrap; }
In quirks mode, the following rules are also expected to apply:
@namespace "http://www.w3.org/1999/xhtml" ;
form { margin-block-end : 1 em ; }
The center element, and the div element when it
has an
align attribute whose
value is
an ASCII
case-insensitive match for either the string "center" or the string
"middle", are expected to center text within themselves, as if they had
their 'text-align' property set to 'center' in a presentational hint,
and to
align descendants to the
center.
The div element,
when it
has an
align
attribute whose value is an ASCII
case-insensitive match for the string "left", is expected to left-align
text within
itself,
as if it had its
'text-align' property set to 'left' in a presentational hint,
and to
align descendants to the
left.
The div element,
when it
has an
align
attribute whose value is an ASCII
case-insensitive match for the string "right", is expected to right-align
text
within
itself, as if it had its
'text-align' property set to 'right' in a presentational hint,
and to
align descendants to the
right.
The div element,
when it
has an
align
attribute whose value is an ASCII
case-insensitive match for the string "justify", is expected to
full-justify text
within
itself, as if it had its
'text-align' property set to 'justify' in a presentational hint,
and to
align descendants to the
left.
@namespace "http://www.w3.org/1999/xhtml" ;
cite, dfn, em, i, var { font-style : italic; }
b, strong { font-weight : bolder; }
code, kbd, samp, tt { font-family : monospace; }
big { font-size : larger; }
small { font-size : smaller; }
sub { vertical-align : sub; }
sup { vertical-align : super; }
sub, sup { line-height : normal; font-size : smaller; }
ruby { display : ruby; }
rt { display : ruby-text; }
:link { color : #0000EE; }
:visited { color : #551A8B; }
:link:active, :visited:active { color : #FF0000; }
:link, :visited { text-decoration : underline; cursor : pointer; }
:focus-visible { outline : auto; }
mark { background : yellow; color : black; } /* this color is just a suggestion and can be changed based on implementation feedback */
abbr[title], acronym[title] { text-decoration : dotted underline; }
ins, u { text-decoration : underline; }
del, s, strike { text-decoration : line-through; }
q::before { content : open-quote; }
q::after { content : close-quote; }
br { display-outside : newline; } /* this also has bidi implications */
nobr { white-space : nowrap; }
wbr { display-outside : break-opportunity; } /* this also has bidi implications */
nobr wbr { white-space : normal; }
The following rules are also expected to apply, as presentational hints:
@namespace "http://www.w3.org/1999/xhtml" ;
br[clear=left i] { clear : left; }
br[clear=right i] { clear : right; }
br[clear=all i], br[clear=both i] { clear : both; }
For the purposes of the CSS ruby model, runs of children of ruby elements
that are
not rt or rp elements are
expected to
be
wrapped in anonymous boxes
whose 'display' property has the value 'ruby-base'. [CSSRUBY]
When a particular part of a ruby has more than one annotation, the annotations should be distributed on both sides of the base text so as to minimize the stacking of ruby annotations on one side.
When it becomes possible to do so, the preceding requirement will be updated to be
expressed in terms of CSS ruby. (Currently, CSS ruby does not handle nested ruby
elements or multiple sequential rt elements, which
is how
this
semantic is
expressed.)
User agents that do not support correct ruby rendering are expected to render parentheses
around the text of rt
elements
in the absence of rp
elements.
User agents are expected to support the 'clear'
property on
inline
elements (in
order to render br
elements with
clear
attributes) in the manner described in the non-normative note to this effect in
CSS.
The initial value for the 'color' property is expected to be black. The initial value for the 'background-color' property is expected to be 'transparent'. The canvas's background is expected to be white.
When a font element has a
color
attribute, its value is expected to be parsed using the rules for parsing a legacy
color
value, and if that does not return an error, the user agent is expected to treat the
attribute as a presentational
hint setting the
element's 'color'
property to the resulting color.
When a font element has a
face
attribute, the user agent is expected to treat the attribute as a presentational hint setting the element's
'font-family' property to the
attribute's value.
When a font element has a
size
attribute, the user agent is expected to use the following steps, known as the rules for
parsing a legacy font size, to treat the attribute as a presentational hint setting the element's
'font-size' property:
Let input be the attribute's value.
Let position be a pointer into input, initially pointing at the start of the string.
Skip ASCII whitespace within input given position.
If position is past the end of input, there is no presentational hint. Return.
If the character at position is a U+002B PLUS SIGN character (+), then let mode be relative-plus, and advance position to the next character. Otherwise, if the character at position is a U+002D HYPHEN-MINUS character (-), then let mode be relative-minus, and advance position to the next character. Otherwise, let mode be absolute.
Collect a sequence of code points that are ASCII digits from input given position, and let the resulting sequence be digits.
If digits is the empty string, there is no presentational hint. Return.
Interpret digits as a base-ten integer. Let value be the resulting number.
If mode is relative-plus, then increment value by 3. If mode is relative-minus, then let value be the result of subtracting value from 3.
If value is greater than 7, let it be 7.
If value is less than 1, let it be 1.
Set 'font-size' to the keyword corresponding to the value of value according to the following table:
| value | 'font-size' keyword |
|---|---|
| 1 | 'x-small' |
| 2 | 'small' |
| 3 | 'medium' |
| 4 | 'large' |
| 5 | 'x-large' |
| 6 | 'xx-large' |
| 7 | 'xxx-large' |
@namespace "http://www.w3.org/1999/xhtml" ;
[dir]:dir(ltr), bdi:dir(ltr), input[type=tel i]:dir(ltr) { direction : ltr; }
[dir]:dir(rtl), bdi:dir(rtl) { direction : rtl; }
address, blockquote, center, div, figure, figcaption, footer, form, header, hr,
legend, listing, main, p, plaintext, pre, summary, xmp, article, aside, h1, h2,
h3, h4, h5, h6, hgroup, nav, section, search, table, caption, colgroup, col,
thead, tbody, tfoot, tr, td, th, dir, dd, dl, dt, menu, ol, ul, li, bdi, output,
[dir=ltr i], [dir=rtl i], [dir=auto i] {
unicode-bidi : isolate;
}
bdo, bdo[dir] { unicode-bidi : isolate-override; }
input[dir=auto i]:is([type=search i], [type=tel i], [type=url i],
[type=email i]), textarea[dir=auto i], pre[dir=auto i] {
unicode-bidi : plaintext;
}
/* see prose for input elements whose type attribute is in the Text state */
/* the rules setting the 'content' property on br and wbr elements also has bidi implications */
When an input
element's
dir attribute is in the
auto state and its type
attribute is in the Text state,
then the
user
agent is
expected to act as if it had a user-agent-level style sheet rule setting the
'unicode-bidi' property to 'plaintext'.
Input fields (i.e. textarea
elements, and input
elements
when their
type attribute is
in the
Text, Search,
Telephone, URL,
or Email
state) are
expected to present an editing
user interface with a directionality that matches the element's 'direction'
property.
When the document's character encoding is ISO-8859-8, the following rules are additionally expected to apply, following those above: [ENCODING]
@namespace "http://www.w3.org/1999/xhtml" ;
address, blockquote, center, div, figure, figcaption, footer, form, header, hr,
legend, listing, main, p, plaintext, pre, summary, xmp, article, aside, h1, h2,
h3, h4, h5, h6, hgroup, nav, section, search, table, caption, colgroup, col,
thead, tbody, tfoot, tr, td, th, dir, dd, dl, dt, menu, ol, ul, li, [dir=ltr i],
[dir=rtl i], [dir=auto i], *|* {
unicode-bidi : bidi-override;
}
input:not([type=submit i]):not([type=reset i]):not([type=button i]),
textarea {
unicode-bidi : normal;
}
@namespace "http://www.w3.org/1999/xhtml" ;
article, aside, h1, h2, h3, h4, h5, h6, hgroup, nav, section {
display : block;
}
h1 { margin-block : 0.67 em ; font-size : 2.00 em ; font-weight : bold; }
h2 { margin-block : 0.83 em ; font-size : 1.50 em ; font-weight : bold; }
h3 { margin-block : 1.00 em ; font-size : 1.17 em ; font-weight : bold; }
h4 { margin-block : 1.33 em ; font-size : 1.00 em ; font-weight : bold; }
h5 { margin-block : 1.67 em ; font-size : 0.83 em ; font-weight : bold; }
h6 { margin-block : 2.33 em ; font-size : 0.67 em ; font-weight : bold; }
In the following CSS block, x is shorthand for the following selector:
:is(article, aside, nav, section)
@namespace "http://www.w3.org/1999/xhtml" ;
x h1 { margin-block : 0.83 em ; font-size : 1.50 em ; }
x x h1 { margin-block : 1.00 em ; font-size : 1.17 em ; }
x x x h1 { margin-block : 1.33 em ; font-size : 1.00 em ; }
x x x x h1 { margin-block : 1.67 em ; font-size : 0.83 em ; }
x x x x x h1 { margin-block : 2.33 em ; font-size : 0.67 em ; }
The shorthand is used to keep this block at least mildly readable.
@namespace "http://www.w3.org/1999/xhtml" ;
dir, dd, dl, dt, menu, ol, ul { display : block; }
li { display : list-item; text-align : match-parent; }
dir, dl, menu, ol, ul { margin-block : 1 em ; }
:is(dir, dl, menu, ol, ul) :is(dir, dl, menu, ol, ul) {
margin-block : 0 ;
}
dd { margin-inline-start : 40 px ; }
dir, menu, ol, ul { padding-inline-start : 40 px ; }
ol, ul, menu { counter-reset : list-item; }
ol { list-style-type : decimal; }
dir, menu, ul {
list-style-type : disc;
}
:is(dir, menu, ol, ul) :is(dir, menu, ul) {
list-style-type : circle;
}
:is(dir, menu, ol, ul) :is(dir, menu, ol, ul) :is(dir, menu, ul) {
list-style-type : square;
}
The following rules are also expected to apply, as presentational hints:
@namespace "http://www.w3.org/1999/xhtml" ;
ol[type="1"], li[type="1"] { list-style-type : decimal; }
ol[type=a s], li[type=a s] { list-style-type : lower-alpha; }
ol[type=A s], li[type=A s] { list-style-type : upper-alpha; }
ol[type=i s], li[type=i s] { list-style-type : lower-roman; }
ol[type=I s], li[type=I s] { list-style-type : upper-roman; }
ul[type=none i], li[type=none i] { list-style-type : none; }
ul[type=disc i], li[type=disc i] { list-style-type : disc; }
ul[type=circle i], li[type=circle i] { list-style-type : circle; }
ul[type=square i], li[type=square i] { list-style-type : square; }
When rendering li elements,
non-CSS user
agents
are expected to use the
ordinal value of the li element to render the
counter in the
list
item
marker.
For CSS user agents, some aspects of rendering list items are defined by the CSS Lists specification. Additionally, the following attribute mappings are expected to apply: [CSSLISTS]
When an li element has a value attribute, and parsing that
attribute's value
using the
rules for parsing
integers
doesn't
generate an error, the user agent is expected to
use the parsed value value as a presentational
hint for the 'counter-set' property of the form list-item
value.
When an ol element has a start
attribute or a reversed
attribute,
or both,
the user agent
is expected to use the following steps to treat the attributes as a presentational hint for the
'counter-reset' property:
Let value be null.
If the element has a start
attribute,
then set
value to the result of parsing the attribute's value using the rules for
parsing integers.
If the element has a reversed
attribute, then:
If value is an integer, then increment value by 1 and
return
reversed(list-item) value.
Otherwise, return reversed(list-item).
Either the start
attribute was absent, or
parsing its value resulted in an error.
Otherwise:
If value is an integer, then decrement value by 1 and
return
list-item value.
Otherwise, there is no presentational hint.
@namespace "http://www.w3.org/1999/xhtml" ;
table { display : table; }
caption { display : table-caption; }
colgroup, colgroup[hidden] { display : table-column-group; }
col, col[hidden] { display : table-column; }
thead, thead[hidden] { display : table-header-group; }
tbody, tbody[hidden] { display : table-row-group; }
tfoot, tfoot[hidden] { display : table-footer-group; }
tr, tr[hidden] { display : table-row; }
td, th { display : table-cell; }
colgroup[hidden], col[hidden], thead[hidden], tbody[hidden],
tfoot[hidden], tr[hidden] {
visibility : collapse;
}
table {
box-sizing : border-box;
border-spacing : 2 px ;
border-collapse : separate;
text-indent : initial;
}
td, th { padding : 1 px ; }
th { font-weight : bold; }
caption { text-align : center; }
thead, tbody, tfoot, table > tr { vertical-align : middle; }
tr, td, th { vertical-align : inherit; }
thead, tbody, tfoot, tr { border-color : inherit; }
table[rules=none i], table[rules=groups i], table[rules=rows i],
table[rules=cols i], table[rules=all i], table[frame=void i],
table[frame=above i], table[frame=below i], table[frame=hsides i],
table[frame=lhs i], table[frame=rhs i], table[frame=vsides i],
table[frame=box i], table[frame=border i],
table[rules=none i] > tr > td, table[rules=none i] > tr > th,
table[rules=groups i] > tr > td, table[rules=groups i] > tr > th,
table[rules=rows i] > tr > td, table[rules=rows i] > tr > th,
table[rules=cols i] > tr > td, table[rules=cols i] > tr > th,
table[rules=all i] > tr > td, table[rules=all i] > tr > th,
table[rules=none i] > thead > tr > td, table[rules=none i] > thead > tr > th,
table[rules=groups i] > thead > tr > td, table[rules=groups i] > thead > tr > th,
table[rules=rows i] > thead > tr > td, table[rules=rows i] > thead > tr > th,
table[rules=cols i] > thead > tr > td, table[rules=cols i] > thead > tr > th,
table[rules=all i] > thead > tr > td, table[rules=all i] > thead > tr > th,
table[rules=none i] > tbody > tr > td, table[rules=none i] > tbody > tr > th,
table[rules=groups i] > tbody > tr > td, table[rules=groups i] > tbody > tr > th,
table[rules=rows i] > tbody > tr > td, table[rules=rows i] > tbody > tr > th,
table[rules=cols i] > tbody > tr > td, table[rules=cols i] > tbody > tr > th,
table[rules=all i] > tbody > tr > td, table[rules=all i] > tbody > tr > th,
table[rules=none i] > tfoot > tr > td, table[rules=none i] > tfoot > tr > th,
table[rules=groups i] > tfoot > tr > td, table[rules=groups i] > tfoot > tr > th,
table[rules=rows i] > tfoot > tr > td, table[rules=rows i] > tfoot > tr > th,
table[rules=cols i] > tfoot > tr > td, table[rules=cols i] > tfoot > tr > th,
table[rules=all i] > tfoot > tr > td, table[rules=all i] > tfoot > tr > th {
border-color : black;
}
The following rules are also expected to apply, as presentational hints:
@namespace "http://www.w3.org/1999/xhtml" ;
table[align=left i] { float : left; }
table[align=right i] { float : right; }
table[align=center i] { margin-inline : auto; }
thead[align=absmiddle i], tbody[align=absmiddle i], tfoot[align=absmiddle i],
tr[align=absmiddle i], td[align=absmiddle i], th[align=absmiddle i] {
text-align : center;
}
caption[align=bottom i] { caption-side : bottom; }
p[align=left i], h1[align=left i], h2[align=left i], h3[align=left i],
h4[align=left i], h5[align=left i], h6[align=left i] {
text-align : left;
}
p[align=right i], h1[align=right i], h2[align=right i], h3[align=right i],
h4[align=right i], h5[align=right i], h6[align=right i] {
text-align : right;
}
p[align=center i], h1[align=center i], h2[align=center i], h3[align=center i],
h4[align=center i], h5[align=center i], h6[align=center i] {
text-align : center;
}
p[align=justify i], h1[align=justify i], h2[align=justify i], h3[align=justify i],
h4[align=justify i], h5[align=justify i], h6[align=justify i] {
text-align : justify;
}
thead[valign=top i], tbody[valign=top i], tfoot[valign=top i],
tr[valign=top i], td[valign=top i], th[valign=top i] {
vertical-align : top;
}
thead[valign=middle i], tbody[valign=middle i], tfoot[valign=middle i],
tr[valign=middle i], td[valign=middle i], th[valign=middle i] {
vertical-align : middle;
}
thead[valign=bottom i], tbody[valign=bottom i], tfoot[valign=bottom i],
tr[valign=bottom i], td[valign=bottom i], th[valign=bottom i] {
vertical-align : bottom;
}
thead[valign=baseline i], tbody[valign=baseline i], tfoot[valign=baseline i],
tr[valign=baseline i], td[valign=baseline i], th[valign=baseline i] {
vertical-align : baseline;
}
td[nowrap], th[nowrap] { white-space : nowrap; }
table[rules=none i], table[rules=groups i], table[rules=rows i],
table[rules=cols i], table[rules=all i] {
border-style : hidden;
border-collapse : collapse;
}
table[border] { border-style : outset; } /* only if border is not equivalent to zero */
table[frame=void i] { border-style : hidden; }
table[frame=above i] { border-style : outset hidden hidden hidden; }
table[frame=below i] { border-style : hidden hidden outset hidden; }
table[frame=hsides i] { border-style : outset hidden outset hidden; }
table[frame=lhs i] { border-style : hidden hidden hidden outset; }
table[frame=rhs i] { border-style : hidden outset hidden hidden; }
table[frame=vsides i] { border-style : hidden outset; }
table[frame=box i], table[frame=border i] { border-style : outset; }
table[border] > tr > td, table[border] > tr > th,
table[border] > thead > tr > td, table[border] > thead > tr > th,
table[border] > tbody > tr > td, table[border] > tbody > tr > th,
table[border] > tfoot > tr > td, table[border] > tfoot > tr > th {
/* only if border is not equivalent to zero */
border-width : 1 px ;
border-style : inset;
}
table[rules=none i] > tr > td, table[rules=none i] > tr > th,
table[rules=none i] > thead > tr > td, table[rules=none i] > thead > tr > th,
table[rules=none i] > tbody > tr > td, table[rules=none i] > tbody > tr > th,
table[rules=none i] > tfoot > tr > td, table[rules=none i] > tfoot > tr > th,
table[rules=groups i] > tr > td, table[rules=groups i] > tr > th,
table[rules=groups i] > thead > tr > td, table[rules=groups i] > thead > tr > th,
table[rules=groups i] > tbody > tr > td, table[rules=groups i] > tbody > tr > th,
table[rules=groups i] > tfoot > tr > td, table[rules=groups i] > tfoot > tr > th,
table[rules=rows i] > tr > td, table[rules=rows i] > tr > th,
table[rules=rows i] > thead > tr > td, table[rules=rows i] > thead > tr > th,
table[rules=rows i] > tbody > tr > td, table[rules=rows i] > tbody > tr > th,
table[rules=rows i] > tfoot > tr > td, table[rules=rows i] > tfoot > tr > th {
border-width : 1 px ;
border-style : none;
}
table[rules=cols i] > tr > td, table[rules=cols i] > tr > th,
table[rules=cols i] > thead > tr > td, table[rules=cols i] > thead > tr > th,
table[rules=cols i] > tbody > tr > td, table[rules=cols i] > tbody > tr > th,
table[rules=cols i] > tfoot > tr > td, table[rules=cols i] > tfoot > tr > th {
border-width : 1 px ;
border-block-style : none;
border-inline-style : solid;
}
table[rules=all i] > tr > td, table[rules=all i] > tr > th,
table[rules=all i] > thead > tr > td, table[rules=all i] > thead > tr > th,
table[rules=all i] > tbody > tr > td, table[rules=all i] > tbody > tr > th,
table[rules=all i] > tfoot > tr > td, table[rules=all i] > tfoot > tr > th {
border-width : 1 px ;
border-style : solid;
}
table[rules=groups i] > colgroup {
border-inline-width : 1 px ;
border-inline-style : solid;
}
table[rules=groups i] > thead,
table[rules=groups i] > tbody,
table[rules=groups i] > tfoot {
border-block-width : 1 px ;
border-block-style : solid;
}
table[rules=rows i] > tr, table[rules=rows i] > thead > tr,
table[rules=rows i] > tbody > tr, table[rules=rows i] > tfoot > tr {
border-block-width : 1 px ;
border-block-style : solid;
}
In quirks mode, the following rules are also expected to apply:
@namespace "http://www.w3.org/1999/xhtml" ;
table {
font-weight : initial;
font-style : initial;
font-variant : initial;
font-size : initial;
line-height : initial;
white-space : initial;
text-align : initial;
}
For the purposes of the CSS table model, the col element is expected to
be
treated
as if it was present as many times as its span
attribute specifies.
For the purposes of the CSS table model, the colgroup element,
if it
contains
no
col element, is expected
to be
treated
as if it had as many such children as its
span attribute specifies.
For the purposes of the CSS table model, the colspan and
rowspan attributes on
td and th
elements are expected to provide the
special knowledge regarding cells spanning rows and columns.
In HTML documents, the following rules are also expected to apply:
@namespace "http://www.w3.org/1999/xhtml" ;
:is(table, thead, tbody, tfoot, tr) > form { display : none !important; }
The table element's
cellspacing
attribute maps
to the
pixel length property 'border-spacing' on the
element.
The table element's
cellpadding
attribute maps to
the
pixel length
properties 'padding-top', 'padding-right',
'padding-bottom', and 'padding-left' of any td and
th elements that have
corresponding cells in the
table corresponding to the table element.
The table element's
height attribute
maps to the
dimension
property 'height' on the table
element.
The table element's
width attribute
maps to the dimension property
(ignoring
zero) 'width' on the
table element.
The col element's width attribute maps
to the dimension property 'width'
on the
col
element.
The thead, tbody, and tfoot elements' height attribute maps to
the
dimension
property
'height' on the element.
The tr element's height attribute maps
to the dimension property 'height' on
the tr element.
The td and th elements' height
attributes map to the dimension
property (ignoring zero) 'height' on
the
element.
The td and th elements' width
attributes map to the dimension
property (ignoring zero) 'width'
on the
element.
The thead, tbody, tfoot, tr,
td, and th elements, when they have
an
align
attribute whose value is an ASCII
case-insensitive match for either the string "center" or the string
"middle",
are expected to center
text within themselves, as if they had their 'text-align'
property set to 'center' in
a presentational hint, and
to align
descendants to the center.
The thead, tbody, tfoot, tr,
td, and th elements, when they have
an
align
attribute whose value is an ASCII
case-insensitive match for the string "left", are expected to left-align
text
within
themselves, as if they had their
'text-align' property set to 'left' in a presentational hint, and
to align descendants to the left.
The thead, tbody, tfoot, tr,
td, and th elements, when they have
an
align
attribute whose value is an ASCII
case-insensitive match for the string "right", are expected to right-align
text
within
themselves, as if they had their
'text-align' property set to 'right' in a presentational hint, and
to align descendants to the
right.
The thead, tbody, tfoot, tr,
td, and th elements, when they have
an
align
attribute whose value is an ASCII
case-insensitive match for the string "justify", are expected to
full-justify text
within
themselves, as if they had
their 'text-align' property set to 'justify' in a presentational hint, and
to align descendants to the left.
User agents are expected to have a rule in their user agent style sheet that matches
th elements that have a
parent
node whose
computed value for the
'text-align' property is its initial value, whose
declaration
block
consists of just
a single declaration that sets the 'text-align'
property to the value 'center'.
When a table, thead, tbody, tfoot,
tr, td, or th element has a background attribute set to
a
non-empty
value, the new value is
expected to be encoding-parsed-and-serialized
relative to
the
element's node document,
and if that does not return failure, the user agent is expected to treat the attribute as a presentational hint
setting the
element's
'background-image' property to the return value.
When a table, thead, tbody, tfoot,
tr, td, or th element has a
bgcolor
attribute set, the new value is expected to be parsed using the rules
for parsing a legacy
color value, and if that does not return an error, the user agent is expected to treat
the
attribute as a presentational
hint
setting
the element's
'background-color' property to the resulting color.
When a table element
has a
bordercolor
attribute, its value is expected to be parsed using the rules for parsing a legacy color
value, and if that does not return an error, the user agent is expected to treat the
attribute as a presentational
hint
setting
the
element's 'border-top-color', 'border-right-color',
'border-bottom-color', and 'border-left-color' properties to the
resulting color.
The table element's
border attribute maps
to the
pixel
length properties
'border-top-width', 'border-right-width',
'border-bottom-width', 'border-left-width' on the element. If the
attribute is present but parsing the attribute's value using the rules
for parsing
non-negative integers generates an error, a default value of 1px is expected to be used
for
that property instead.
Rules marked "only if border is not equivalent to zero"
in the CSS block above is expected to only be applied if the border attribute
mentioned in
the
selectors for the rule is not
only present but, when parsed using the rules for parsing non-negative
integers,
is
also found to have a value other than zero or to generate an error.
In quirks mode, a td element or a th element that has a
nowrap attribute but
also has a
width attribute whose
value,
when parsed
using the rules for
parsing nonzero dimension values, is found to be a length (not an error or a number
classified as a percentage), is expected to have a presentational hint setting the element's 'white-space' property to
'normal', overriding the rule in the CSS block above that sets it to 'nowrap'.
A node is substantial if it is a text node that is not inter-element whitespace, or if it is an element node.
A node is blank if it is an element that contains no substantial nodes.
The elements with default margins
are the following elements: blockquote,
dir, dl,
h1,
h2,
h3,
h4,
h5,
h6,
listing, menu,
ol,
p, plaintext, pre, ul, xmp
In quirks
mode, any element
with default margins that is the child
of a
body,
td, or th element and
has no
substantial previous
siblings is
expected to
have a
user-agent level style sheet rule that sets its 'margin-block-start' property to
zero.
In quirks
mode, any element
with default margins that is the child of a
body,
td, or
th
element, has no
substantial previous
siblings, and
is blank, is
expected to
have a user-agent level style sheet
rule that sets its 'margin-block-end' property to zero also.
In quirks
mode, any element
with default margins that is the child of a
td or
th
element, has no
substantial following
siblings, and
is blank, is
expected
to have a user-agent level style sheet
rule that sets its 'margin-block-start' property to zero.
In quirks
mode, any p
element that
is the
child of a td or th element
and has
no substantial following
siblings, is
expected
to have a user-agent level style sheet rule that sets its 'margin-block-end' property
to zero.
@namespace "http://www.w3.org/1999/xhtml" ;
input, select, button, textarea {
letter-spacing : initial;
word-spacing : initial;
line-height : initial;
text-transform : initial;
text-indent : initial;
text-shadow : initial;
appearance : auto;
}
input:not([type=image i], [type=range i], [type=checkbox i], [type=radio i]) {
overflow : clip !important;
overflow-clip-margin: 0 !important;
}
input, select, textarea {
text-align: initial;
}
:autofill {
field-sizing: fixed !important;
}
input:is([type=reset i], [type=button i], [type=submit i]), button {
text-align: center;
}
input, button {
display: inline-block;
}
input[type=hidden i], input[type=file i], input[type=image i] {
appearance: none;
}
input:is([type=radio i], [type=checkbox i], [type=reset i], [type=button i],
[type=submit i], [type=color i], [type=search i]), select, button {
box-sizing: border-box;
}
textarea { white-space: pre-wrap; }
In quirks mode, the following rules are also expected to apply:
@namespace "http://www.w3.org/1999/xhtml" ;
input:not([type=image i]), textarea { box-sizing : border-box; }
Each kind of form control is also described in the Widgets section, which describes the look and feel of the control.
For input elements
where
the type attribute
is not in the
state or the Image
Button state, and that are being
rendered, are expected to act as follows:
The inner display type is always 'flow-root'.
hr element@namespace "http://www.w3.org/1999/xhtml" ;
hr {
color : gray;
border-style : inset;
border-width : 1 px ;
margin-block : 0.5 em ;
margin-inline : auto;
overflow : hidden;
}
The following rules are also expected to apply, as presentational hints:
@namespace "http://www.w3.org/1999/xhtml" ;
hr[align=left i] { margin-left : 0 ; margin-right : auto; }
hr[align=right i] { margin-left : auto; margin-right : 0 ; }
hr[align=center i] { margin-left : auto; margin-right : auto; }
hr[color], hr[noshade] { border-style : solid; }
If an hr element
has either
a color attribute
or a noshade
attribute,
and
furthermore also has a size
attribute,
and parsing that attribute's value using the
rules for parsing non-negative
integers
doesn't generate an error, then the user
agent is expected to use the parsed value divided by two as a pixel length for
presentational
hints for
the
properties 'border-top-width',
'border-right-width', 'border-bottom-width', and
'border-left-width' on the element.
Otherwise, if an hr
element
has
neither a color
attribute nor a noshade
attribute, but does have a size
attribute, and parsing that attribute's value using the
rules for parsing non-negative
integers
doesn't generate an error, then: if the
parsed value is one, then the user agent is expected to use the attribute as a presentational
hint
setting the element's
'border-bottom-width' to 0; otherwise, if the
parsed
value is
greater than one, then
the user agent is expected to use the parsed value minus two as a pixel length for
presentational
hints for
the 'height' property on the element.
The width attribute on
an hr element maps
to the dimension property 'width'
on the
element.
When an hr element
has a
color attribute, its
value is expected to be parsed using the rules for parsing a legacy color
value, and
if that does not return an error, the user agent is expected to treat the attribute as a presentational
hint
setting the
element's
'color' property to the resulting color.
fieldset
and legend
elements@namespace "http://www.w3.org/1999/xhtml" ;
fieldset {
display : block;
margin-inline : 2 px ;
border : groove 2 px ThreeDFace;
padding-block : 0.35 em 0.625 em ;
padding-inline : 0.75 em ;
min-inline-size : min-content;
}
legend {
padding-inline : 2 px ;
}
legend[align=left i] {
justify-self : left;
}
legend[align=center i] {
justify-self : center;
}
legend[align=right i] {
justify-self : right;
}
The fieldset
element, when it generates a CSS box, is
expected
to act
as follows:
The element is expected to establish a new block formatting context.
The 'display' property is expected to act as follows:
If the computed value of 'display' is a value such that the outer display type is 'inline', then behave as 'inline-block'.
Otherwise, behave as 'flow-root'.
This does not change the computed value.
If the element's box has a child box that matches the conditions in the list below, then the first such child box is the 'fieldset' element's rendered legend:
legend
element.
If the element has a rendered legend, then the border is expected to not be painted behind the rectangle defined as follows, using the writing mode of the fieldset:
The block-start edge of the rectangle is the smaller of the block-start edge of
the
rendered
legend's margin rectangle at its static position (ignoring transforms),
and the block-start outer edge of the fieldset's
border.
The block-end edge of the rectangle is the larger of the block-end edge of the
rendered
legend's margin rectangle at its static position (ignoring transforms),
and the block-end outer edge of the fieldset's
border.
The inline-start edge of the rectangle is the smaller of the inline-start edge of
the
rendered
legend's border rectangle at its static position (ignoring transforms),
and the inline-start outer edge of the fieldset's
border.
The inline-end edge of the rectangle is the larger of the inline-end edge of the
rendered
legend's border rectangle at its static position (ignoring transforms),
and the inline-end outer edge of the fieldset's
border.
The space allocated for the element's border on the block-start side is expected to be
the element's 'border-block-start-width' or the
rendered
legend's
margin box size in the fieldset's
block-flow direction, whichever is
greater.
For the purpose of calculating the used 'block-size', if the computed 'block-size' is not 'auto', the space allocated for the rendered legend's margin box that spills out past the border, if any, is expected to be subtracted from the 'block-size'. If the content box's block-size would be negative, then let the content box's block-size be zero instead.
If the element has a rendered legend, then that element is expected to be the first child box.
The anonymous
fieldset
content
box is expected to appear after the
rendered
legend and
is expected to contain the content (including the '::before'
and '::after' pseudo-elements) of the fieldset
element except for the
rendered
legend, if
there is one.
The used value of the 'padding-top', 'padding-right', 'padding-bottom', and 'padding-left' properties are expected to be zero.
For the purpose of calculating the min-content inline size, use the greater of the min-content inline size of the rendered legend and the min-content inline size of the anonymous fieldset content box.
For the purpose of calculating the max-content inline size, use the greater of the max-content inline size of the rendered legend and the max-content inline size of the anonymous fieldset content box.
A fieldset
element's rendered
legend,
if any, is expected to act as
follows:
The element is expected to establish a new formatting context for its contents. The type of this formatting context is determined by its 'display' value, as usual.
The 'display' property is expected to behave as if its computed value was blockified.
This does not change the computed value.
If the computed value of 'inline-size' is 'auto', then the used value is the fit-content inline size.
The element is expected to be positioned in the inline direction as is normal for blocks (e.g., taking into account margins and the 'justify-self' property).
The element's box is expected to be constrained in the inline direction by the inline
content size of the fieldset
as if it had used its computed inline padding.
For example, if the fieldset
has a specified padding of 50px, then the
rendered
legend
will be positioned 50px in from the fieldset's
border. The padding will further apply to the anonymous
fieldset
content
box
instead of the fieldset
element itself.
The element is expected to be positioned in the block-flow direction such that its border
box is centered over the border on the block-start side of the fieldset
element.
A fieldset
element's anonymous fieldset content box is
expected to
act as follows:
The 'display' property is expected to act as follows:
The following properties are expected to inherit from the fieldset
element:
The 'block-size' property is expected to be set to '100%'.
For the purpose of calculating percentage padding, act as if the padding was calculated
for the fieldset
element.
The following elements can be replaced
elements: audio,
canvas,
embed, iframe,
img, input, object, and
video.
The embed,
iframe,
and
video
elements
are expected to be
treated as replaced
elements.
A canvas
element that represents
embedded
content is
expected to be treated as a replaced
element; the contents of such elements are the
element's bitmap, if any, or else a transparent
black bitmap with the same
natural
dimensions as the element. Other canvas
elements are expected
to be treated as ordinary elements in the rendering model.
An object
element that represents
an
image,
plugin, or its
content
navigable
is
expected to be treated as a replaced
element.
Other object
elements are expected to be treated as ordinary elements in the
rendering model.
The audio
element, when it is exposing a user
interface, is
expected to be treated as a
replaced
element about one line high, as wide as is necessary to expose the user
agent's user interface features. When an audio
element
is not exposing a user
interface, the
user agent is expected to force
its 'display'
property to compute to 'none', irrespective of CSS rules.
Whether a video
element
is exposing a user
interface is
not expected to affect the size of the rendering;
controls are expected to be overlaid above the page content without causing any layout changes,
and are expected to disappear when the user does not need them.
When a video
element represents a poster frame or frame of video, the poster frame
or frame of video is expected to be rendered at the largest size that maintains the aspect ratio
of that poster frame or frame of video without being taller or wider than the video
element itself, and is expected to be centered in the video
element.
Any subtitles or captions are expected to be overlaid directly on top of their
video
element, as defined by the relevant rendering rules; for WebVTT, those are the
rules for updating the
display
of
WebVTT text tracks. [WEBVTT]
When the user agent starts exposing a user
interface for a video
element,
the user agent should run the rules for
updating the text track rendering of each of the text
tracks in the video
element's list of
text
tracks that are showing and whose text track
kind is one
of subtitles
or captions
(e.g., for text
tracks based on WebVTT, the rules for updating the
display
of
WebVTT text
tracks). [WEBVTT]
Resizing video
and
canvas
elements does not interrupt
video playback or clear the canvas.
The following CSS rules are expected to apply:
@namespace "http://www.w3.org/1999/xhtml" ;
iframe { border : 2 px inset; }
video { object-fit : contain; }
User agents are expected to render img
elements and input
elements
whose type attributes are
in the
Image
Button
state, according to the first applicable rules
from the following list:
alt attribute, or
Document is in quirks mode, and the element already has
natural dimensions (e.g., from the dimension
attributes or
CSS
rules)
input elements,
the
element
is expected to appear button-like to indicate that the element is a button.
img
element
that represents some text and the
user agent does not expect this to change
img
element
that represents nothing and the
user agent does not expect this to change
input
element that does not represent an image
and the
user agent
does not expect this to change
The icons mentioned above are expected to be relatively small so as not to disrupt most text but be easily clickable. In a visual environment, for instance, icons could be 16 pixels by 16 pixels square, or 1em by 1em if the images are scalable. In an audio environment, the icon could be a short bleep. The icons are intended to indicate to the user that they can be used to get to whatever options the UA provides for images, and, where appropriate, are expected to provide access to the context menu that would have come up if the user interacted with the actual image.
All animated images with the same absolute URL and the same image data are expected to be rendered synchronized to the same timeline as a group, with the timeline starting at the time of the least recent addition to the group.
In other words, when a second image with the same absolute URL and animated image data is inserted into a document, it jumps to the point in the animation cycle that is currently being displayed by the first image.
When a user agent is to restart the animation for an img element
showing an animated image, all animated images with the same absolute
URL
and the
same image data in that img
element's node document are expected to restart
their animation from the beginning.
The following CSS rules are expected to apply:
@namespace "http://www.w3.org/1999/xhtml" ;
img:is([sizes="auto" i], [sizes^="auto," i]) {
contain : size !important;
contain-intrinsic-size: 300px 150px;
}
The following CSS rules are expected to apply when the Document is in quirks
mode:
@namespace "http://www.w3.org/1999/xhtml" ;
img[align=left i] { margin-right : 3 px ; }
img[align=right i] { margin-left : 3 px ; }
The following CSS rules are expected to apply as presentational hints:
@namespace "http://www.w3.org/1999/xhtml" ;
iframe[frameborder='0'], iframe[frameborder=no i] { border : none; }
embed[align=left i], iframe[align=left i], img[align=left i],
input[type=image i][align=left i], object[align=left i] {
float : left;
}
embed[align=right i], iframe[align=right i], img[align=right i],
input[type=image i][align=right i], object[align=right i] {
float : right;
}
embed[align=top i], iframe[align=top i], img[align=top i],
input[type=image i][align=top i], object[align=top i] {
vertical-align : top;
}
embed[align=baseline i], iframe[align=baseline i], img[align=baseline i],
input[type=image i][align=baseline i], object[align=baseline i] {
vertical-align : baseline;
}
embed[align=texttop i], iframe[align=texttop i], img[align=texttop i],
input[type=image i][align=texttop i], object[align=texttop i] {
vertical-align : text-top;
}
embed[align=absmiddle i], iframe[align=absmiddle i], img[align=absmiddle i],
input[type=image i][align=absmiddle i], object[align=absmiddle i],
embed[align=abscenter i], iframe[align=abscenter i], img[align=abscenter i],
input[type=image i][align=abscenter i], object[align=abscenter i] {
vertical-align : middle;
}
embed[align=bottom i], iframe[align=bottom i], img[align=bottom i],
input[type=image i][align=bottom i], object[align=bottom i] {
vertical-align : bottom;
}
When an embed,
iframe,
img,
or
object
element, or an input
element whose type
attribute is in the Image
Button
state, has
an align attribute whose value is an ASCII
case-insensitive match for
the string "center" or the string "middle", the user
agent is expected to act as if the element's 'vertical-align' property was set to a
value that aligns the vertical middle of the element with the parent element's baseline.
The hspace attribute of embed,
img,
or object
elements, and input
elements with a type
attribute in the Image
Button state, maps to the
dimension
properties 'margin-left'
and 'margin-right' on the element.
The vspace attribute of embed,
img,
or object
elements, and input
elements with a type
attribute in the Image
Button state, maps to the
dimension
properties 'margin-top'
and 'margin-bottom' on the element.
When an img
element, object
element, or input
element
with a type
attribute in the Image
Button
state has
a border attribute whose value, when parsed using the rules
for
parsing non-negative integers, is found to be a number greater than zero, the user agent
is
expected to use the parsed value for eight presentational
hints: four
setting
the
parsed value as a pixel length for the element's 'border-top-width',
'border-right-width', 'border-bottom-width', and
'border-left-width' properties, and four setting
the
element's
'border-top-style', 'border-right-style',
'border-bottom-style', and 'border-left-style' properties to the value
'solid'.
The width
and
height
attributes on an img
element's dimension
attribute
source map to the
dimension
properties
'width'
and 'height' on
the img
element respectively. They
similarly map
to the aspect-ratio property (using dimension rules) of the
img
element.
The width
and height
attributes on embed,
iframe,
object,
and video
elements, and input
elements with a type
attribute in the Image
Button
state and
that either
represents an image or that the user expects will eventually represent an image, map to the
dimension
properties
'width'
and 'height' on
the
element respectively.
The width
and height
attributes map
to the aspect-ratio property (using dimension rules) on
img
and video
elements, and input
elements with a type
attribute in the Image
Button state.
The width
and height
attributes map to the
aspect-ratio
property
on canvas
elements.
Shapes on an image map are expected to act, for
the
purpose of
the CSS cascade, as
elements independent of the original area element that
happen to
match the
same style
rules but inherit from the img
or
object element.
For the purposes of the rendering, only the 'cursor' property is expected to have any effect on the shape.
Thus, for example, if an area element has a
style attribute that sets the 'cursor' property to 'help',
then when the user designates that shape, the cursor would change to a Help cursor.
Similarly, if an area
element had a CSS rule that set its
'cursor' property to 'inherit' (or if no rule setting the 'cursor'
property matched the element at all), the shape's cursor would be inherited from the
img or object element
of the image map, not from the parent
of the area
element.
The CSS Basic User Interface specification calls elements that can have a native appearance widgets, and defines whether to use that native appearance depending on the 'appearance' property. That logic, in turn, depends on whether on whether each the element is classified as a devolvable widget or non-devolvable widget. This section defines which elements match these concepts for HTML, what their native appearance is, and any particularity of their devolved state or primitive appearance. [CSSUI]
The following elements can have a native appearance for the purpose of the CSS 'appearance' property.
Several widgets have their rendering controlled by the 'writing-mode' CSS property. For the purposes of those widgets, we have the following definitions.
A horizontal writing mode is when resolving the 'writing-mode' property of the control results in a computed value of 'horizontal-tb'.
A vertical writing mode is when resolving the 'writing-mode' property of the control results in a computed value of either 'vertical-rl', 'vertical-lr', 'sideways-rl' or 'sideways-lr'.
When an element uses button layout, it is a devolvable widget, and it's native appearance is that of a button.
Button layout is as follows:
If the element is a button
element,
then the
'display' property is
expected to act as follows:
If the computed value of 'display' is 'inline-grid', 'grid', 'inline-flex', 'flex', 'none', or 'contents', then behave as the computed value.
Otherwise, if the computed value of 'display' is a value such that the outer display type is 'inline', then behave as 'inline-block'.
Otherwise, behave as 'flow-root'.
The element is expected to establish a new formatting context for its contents. The type of this formatting context is determined by its 'display' value, as usual.
If the element is absolutely-positioned, then for the purpose of the CSS visual formatting model, act as if the element is a replaced element. [CSS]
If the computed value of 'inline-size' is 'auto', then the used value is the fit-content inline size.
For the purpose of the 'normal' keyword of the 'align-self' property, act as if the element is a replaced element.
If the element is an input
element, or if it is a button
element
and its computed value for 'display'
is not
'inline-grid', 'grid', 'inline-flex',
or 'flex', then the element's box has a child anonymous
button
content box with the
following behaviors:
The box is a block-level block container that establishes a new block formatting context (i.e., 'display' is 'flow-root').
If the box does not overflow in the horizontal axis, then it is centered horizontally.
If the box does not overflow in the vertical axis, then it is centered vertically.
Otherwise, there is no anonymous button content box.
Need to define the expected primitive appearance.
button
elementThe button
element,
when it generates a CSS box, is
expected
to
depict a button and to use button
layout
whose anonymous
button content
box's contents (if there is an anonymous button content box) are
the
child
boxes the element's box would otherwise have.
details
and
summary
elements
@namespace "http://www.w3.org/1999/xhtml" ;
details, summary {
display : block;
}
details > summary:first-of-type {
display : list-item;
counter-increment : list-item 0 ;
list-style : disclosure-closed inside;
}
details[open] > summary:first-of-type {
list-style-type : disclosure-open;
}
The details
element is expected to have an internal shadow
tree
with
three child elements:
The first child element is a slot
that
is expected to take the
details
element's first summary
element child, if any. This element
has a single child summary
element called the default summary which has
text content that is implementation-defined (and probably
locale-specific).
The summary
element that this slot represents
is expected to allow
the user to request the details be shown or hidden.
The second child element is a slot
that is expected to take the
details
element's remaining descendants, if any. This element has no contents.
This element is expected to match the '::details-content' pseudo-element.
This element is expected to have its style
attribute set to
"display: block; content-visibility: hidden;" when the
details
element does not have an open
attribute. When it does have the open
attribute, the
style
attribute is
expected to be set to
"display: block;".
Because the slots are hidden inside a shadow tree, this style
attribute is
not directly visible to author code. Its impacts,
however, are visible. Notably, the choice of content-visibility: hidden
instead of, e.g., display: none, impacts the results of various APIs that
query layout information.
The third child element is either a link
or
style
element with the following styles for the default summary:
:host summary {
display : list-item;
counter-increment : list-item 0 ;
list-style : disclosure-closed inside;
}
:host([open]) summary {
list-style-type : disclosure-open;
}
The position of this child element relative to the other two is not observable. This means that implementations might have it in a different order relative to its siblings. Implementations might even associate the style with the shadow tree using a mechanism that is not an element.
The structure of this shadow tree is observable through the ways that the children
of the details
element and the '::details-content' pseudo-element respond to CSS
styles.
input
element as a text entry widget
An input
element whose type
attribute is in
the Text,
Telephone, URL,
or
Email state, is a
devolvable
widget.
Its
expected native
appearance is to render as an 'inline-block' box depicting
a one-line text control.
An input
element whose type
attribute is in
the Search
state is a devolvable
widget.
Its expected native
appearance is to render as an 'inline-block' box
depicting a one-line text control. If the computed
value
of the element's
'appearance'
property is not 'textfield',
it may have a distinct style
indicating that it is a search field.
An input
element whose type
attribute is in
the Password
state is a
devolvable
widget. Its expected native
appearance is to render as an
'inline-block' box depicting a one-line text control
that
obscures data
entry.
For input
elements whose type
attribute is
in one of the above states, the used
value of
the 'line-height'
property
must be a length value that is no smaller than what the used
value
would be for
'line-height: normal'.
The used value will not be the actual keyword 'normal'. Also, this rule does not affect the computed value.
If these text controls provide a text selection, then, when the user changes the current
selection, the user agent is expected to queue an element task
on the
user
interaction task source given the input
element to fire
an
event named select
at the element, with the bubbles
attribute initialized to
true.
An input
element whose type
attribute is
in one of the above states is an element with default preferred size,
and
user
agents are expected to apply the 'field-sizing'
CSS
property to the element. User
agents are expected to determine the inline
size of
its intrinsic
size
by the following steps:
If the 'field-sizing' property on the element has a computed
value
of 'content', the inline
size is
determined by the text which the element shows. The text is either a
value
or a
short hint specified by the
placeholder
attribute. User agents may take the
text caret size into account in the inline
size.
If the element has a size
attribute, and parsing that
attribute's value using the rules
for
parsing non-negative integers doesn't
generate an error, return the value obtained from applying the converting
a
character
width to pixels algorithm to the value of the attribute.
Otherwise, return the value obtained from applying the converting a character width to pixels algorithm to the number 20.
The converting a character width to pixels algorithm returns (size-1)×avg + max, where size is the character width to convert, avg is the average character width of the primary font for the element for which the algorithm is being run, in pixels, and max is the maximum character width of that same font, also in pixels. (The element's 'letter-spacing' property does not affect the result.)
These text controls are expected to be scroll containers and support scrolling in the inline axis, but not the block axis.
Need to detail the expected native appearance and primitive appearance.
input
element as domain-specific widgets
An input
element whose type
attribute is in
the Date state is a
devolvable
widget
expected to render as an 'inline-block' box depicting a date control.
An input
element whose type
attribute is in
the Month state
is a devolvable
widget
expected to render as an 'inline-block' box depicting a month control.
An input
element whose type
attribute is in
the Week state is a
devolvable
widget
expected to render as an 'inline-block' box depicting a week control.
An input
element whose type
attribute is in
the Time state is a
devolvable
widget
expected to render as an 'inline-block' box depicting a time control.
An input
element whose type
attribute is in
the Local
Date
and Time state is a
devolvable
widget
expected to render as an 'inline-block' box depicting
a local date and time control.
An input
element whose type
attribute is in
the Number
state is a
devolvable
widget
expected to render as an 'inline-block' box depicting a number control.
An input
element whose type
attribute is in
the Number
state is
an
element with default preferred size,
and
user agents
are expected to apply the
'field-sizing'
CSS
property to the element. The block
size of the
intrinsic
size
is about one line high. If the 'field-sizing'
property
on the element has a computed
value
of
'content', the inline
size of
the
intrinsic
size
is expected to be about as wide as necessary to show the current
value.
Otherwise,
the inline
size of
the
intrinsic
size
is expected to be about as wide as necessary to show the widest
possible value.
An input
element whose type
attribute is in
the Date,
Month,
Week, Time,
or Local
Date and Time state, is expected to
be about one line high, and about as wide as necessary to show the widest possible value.
Need to detail the expected native appearance and primitive appearance.
input
element as a range control
An input
element whose type
attribute
is in
the Range state is a non-devolvable
widget. Its expected native
appearance is to render as an
'inline-block' box depicting a slider control.
When this control has a horizontal writing mode, the control is expected to be a horizontal slider. Its lowest value is on the right if the 'direction' property has a computed value of 'rtl', and on the left otherwise. When this control has a vertical writing mode, it is expected to be a vertical slider. Its lowest value is on the bottom if the 'direction' property has a computed value of 'rtl', and on the top otherwise.
Predefined suggested values (provided by the list
attribute) are expected to be shown as tick marks on the slider, which the slider can snap to.
Need to detail the expected primitive appearance.
input
element
as a color
wellAn input
element whose type
attribute is
in
the Color state is expected
to
depict a
color well,
which, when activated, provides the user with a color picker (e.g. a color wheel or color
palette) from which the color can be changed. The element, when it generates a CSS
box, is expected to use button layout, that has no child
boxes of
the
anonymous button content
box.
The anonymous button
content
box is
expected to have a presentational hint setting
the
'background-color' property to the element's value.
Predefined suggested values (provided by the list
attribute) are expected to be shown in the color picker interface, not on the color well
itself.
Need to detail the expected native appearance and primitive appearance.
input
element as a checkbox and radio button widgets
An input
element whose type
attribute is in
the Checkbox
state is a non-devolvable
widget expected to render as an 'inline-block' box containing a single
checkbox control, with no label.
Need to detail the expected native appearance and primitive appearance.
An input
element whose type
attribute is in
the Radio
Button state is a non-devolvable
widget expected to render as an 'inline-block' box containing a single radio
button control, with no label.
Need to detail the expected native appearance and primitive appearance.
input
element as a file upload control
An input
element whose type
attribute is in
the File
Upload state,
when it
generates a CSS
box, is expected to render as an 'inline-block' box containing a span of text
giving the filename(s) of the selected
files, if any, followed by a button that, when activated, provides the user with a file
picker from which the selection can be changed. The button is expected to use button
layout and match the '::file-selector-button' pseudo-element. The
contents
of
its anonymous button
content
box
are expected to be
implementation-defined (and possibly
locale-specific)
text, for
example "Choose
file".
User agents may handle an input
element whose
type
attribute is in the
File
Upload
state as an
element with default preferred size,
and
user agents
may apply the
'field-sizing'
CSS
property to the element. If the 'field-sizing'
property on the element has a computed
value
of
'content', the intrinsic
size
of the
element is expected to depend on its content such as the '::file-selector-button'
pseudo-element and chosen file names.
input
element as a
buttonAn input
element
whose type
attribute
is in
the Submit Button, Reset Button, or Button
state, when it generates a CSS box, is
expected to depict a button and use button layout and the contents of the
anonymous
button content box are expected to be the text of the element's value
attribute, if
any, or text derived from the element's type
attribute in an
implementation-defined (and
probably locale-specific) fashion, if not.
marquee
element@namespace "http://www.w3.org/1999/xhtml" ;
marquee {
display : inline-block;
text-align : initial;
overflow : hidden !important;
}
The marquee
element,
while turned on, is
expected to render in an animated fashion according to its attributes as follows:
behavior
attribute is in the
scroll
state
Slide the contents of the element in the direction described by the direction
attribute as defined below, such that it begins
off the start side of the marquee,
and
ends flush with the inner end side.
For example, if the direction
attribute is left (the default), then
the
contents would start such that their left edge are off the side of the right edge of the
marquee's
content area, and the contents would then slide up
to the
point where the left edge of the contents are flush with the left inner edge of the
marquee's
content area.
Once the animation has ended, the user agent is expected to increment the marquee current loop index. If the element is still turned on after this, then the user agent is expected to restart the animation.
behavior
attribute is in the
slide
state
Slide the contents of the element in the direction described by the direction
attribute as defined below, such that it begins
off the start side of the marquee,
and
ends off the end side of the
marquee.
For example, if the direction
attribute is left (the default), then
the
contents would start such that their left edge are off the side of the right edge of the
marquee's
content area, and the contents would then slide up
to the
point where the right edge of the contents are flush with the left inner edge
of the
marquee's
content area.
Once the animation has ended, the user agent is expected to increment the marquee current loop index. If the element is still turned on after this, then the user agent is expected to restart the animation.
behavior
attribute is in the
alternate state
When the marquee
current loop index is even (or zero), slide the contents of the
element in the direction described by the direction
attribute as defined below, such that it begins flush with the start side of the
marquee,
and ends flush with the end side of the marquee.
When the marquee current loop index
is odd,
slide
the contents of the element in
the opposite direction than that described by the direction
attribute as defined below, such that it begins
flush with the end side of the marquee,
and
ends flush with the start side of the
marquee.
For example, if the direction
attribute is left (the default), then
the
contents would with their right edge flush with the right inner edge of the
marquee's
content area, and the contents would then slide up
to the
point where the left edge of the contents are flush with the left inner edge of
the
marquee's
content area.
Once the animation has ended, the user agent is expected to increment the marquee current loop index. If the element is still turned on after this, then the user agent is expected to continue the animation.
The direction
attribute has the meanings described
in the following table:
direction
attribute state
| Direction of animation | Start edge | End edge | Opposite direction |
|---|---|---|---|---|
| left | ← Right to left | Right | Left | → Left to Right |
| right | → Left to Right | Left | Right | ← Right to left |
| up | ↑ Up (Bottom to Top) | Bottom | Top | ↓ Down (Top to Bottom) |
| down | ↓ Down (Top to Bottom) | Top | Bottom | ↑ Up (Bottom to Top) |
In any case, the animation should proceed such that there is a delay given by the marquee scroll interval between each frame, and such that the content moves at most the distance given by the marquee scroll distance with each frame.
When a marquee
element has a bgcolor
attribute set, the value is expected to be parsed using the rules for parsing a legacy
color
value, and if that does not return an error, the user agent is expected to treat the
attribute as a presentational
hint setting the element's
'background-color' property to the resulting color.
The width and height attributes on a marquee
element
map to
the
dimension properties
'width' and 'height' on
the
element respectively.
The natural height of a marquee
element with
its direction
attribute in the up
or down
states
is 200 CSS
pixels.
The vspace attribute of a
marquee
element maps
to the
dimension
properties 'margin-top'
and 'margin-bottom' on the element. The
hspace attribute of a marquee
element maps
to the dimension properties
'margin-left' and 'margin-right' on the element.
meter
element@namespace "http://www.w3.org/1999/xhtml" ;
meter { appearance : auto; }
The meter
element
is a devolvable widget. Its expected native
appearance is to render as an 'inline-block' box with a 'block-size'
of '1em' and a 'inline-size' of '5em', a 'vertical-align' of '-0.2em', and
with its contents depicting a gauge.
When this element has a horizontal writing mode, the depiction is expected to be of a horizontal gauge. Its minimum value is on the right if the 'direction' property has a computed value of 'rtl', and on the left otherwise. When this element has a vertical writing mode, it is expected to depict a vertical gauge. Its minimum value is on the bottom if the 'direction' property has a computed value of 'rtl', and on the top otherwise.
User agents are expected to use a presentation consistent with platform conventions for gauges, if any.
Requirements for what must be depicted in the gauge are
included in the definition of the meter
element.
Need to detail the expected primitive appearance.
progress
element@namespace "http://www.w3.org/1999/xhtml" ;
progress { appearance : auto; }
The progress
element is a devolvable
widget. Its expected
native appearance is to render as an 'inline-block' box with a
'block-size' of '1em' and a 'inline-size' of '10em', and a
'vertical-align' of '-0.2em'.
When
the this
element has a horizontal
writing mode, the element is expected to be depicted as a
horizontal progress bar. The start is on the right and the end is on the left if the
'direction' property on this element has a computed value of 'rtl', and
with the start on the left and the end on the right otherwise. When this element has a
vertical writing
mode, it is
expected to be depicted as a vertical progress bar. The
start is on the bottom and the end is on the top if the 'direction'
property on this
element has a computed
value
of 'rtl', and with the start on the top and the end on
the bottom otherwise.
User agents are expected to use a presentation consistent with platform conventions for progress bars. In particular, user agents are expected to use different presentations for determinate and indeterminate progress bars. User agents are also expected to vary the presentation based on the dimensions of the element.
Requirements for how to determine if the progress bar is determinate or
indeterminate, and what progress a determinate progress bar is to show, are included in the
definition of the progress
element.
Need to detail the expected primitive appearance.
select
elementThe select
element is
an element with default preferred size,
and
user agents are expected to apply the 'field-sizing'
CSS
property to
select
elements.
A select
element is
either a list box or a drop-down box, depending on its
attributes.
A select
element whose
multiple
attribute is present is expected to render as a multi-select list box.
A select
element whose
multiple
attribute is absent, and whose display
size is greater
than 1, is expected to render as a single-select list
box.
When the element renders as a list box,
it is a
devolvable widget
expected to render as an 'inline-block' box. The inline
size of
its
intrinsic size is the width of the select's
labels
plus
the width of a scrollbar. The block
size of its
intrinsic size is
determined by the following steps:
If the 'field-sizing' property on the element has a computed value of 'content', return the height necessary to contain all rows for items.
If the size
attribute
is absent or it has no valid
value, return the height necessary to contain four rows.
Otherwise, return the height necessary to contain as many rows for items as given by the element's display size.
A select
element whose
multiple
attribute is absent, and whose display size is 1, is
expected to render as an 'inline-block' one-line drop-down box.
The inline
size of its intrinsic
size
is the
width
of the
select's labels. If the 'field-sizing'
property on the element has a computed
value
of
'content',
the inline
size of the
intrinsic size depends on the shown text. The shown text
is
typically the
label of
an option of
which selectedness
is
set to true.
When the element renders as a drop-down
box,
it is a devolvable
widget. Its appearance in the devolved state, as well as its appearance when the
computed value of the element's 'appearance'
property is
'menulist-button',
is that of a drop-down box, including a "drop-down button",
but not necessarily rendered using a native control of the host operating system. In such a
state,
CSS properties such as 'color',
'background-color', and 'border' should
not be disregarded (as is generally permissible when rendering an element according to its
native appearance).
In either case (list box or drop-down box), the
element's items
are
expected to be the element's list of options,
with the element's optgroup
element children
providing headers for groups of options where applicable.
An optgroup
element
is expected to be rendered by displaying the element's label
attribute.
An option
element is
expected to be rendered by displaying the element's label, indented under its optgroup
element if
it
has one.
Each sequence of one or more child hr element
siblings may be
rendered as a single
separator.
The width of the select's labels is the
wider
of the
width necessary to
render the widest optgroup,
and the
width necessary to render the widest
option
element
in the
element's list
of
options (including its indent, if any).
If a select
element
contains a placeholder
label
option, the user
agent is expected to render that option
in a
manner that
conveys that it is a label,
rather than a valid option of the control. This can include preventing the placeholder label
option from being explicitly selected by the user. When the placeholder label
option's selectedness is true, the control
is expected to be displayed in a fashion that indicates that no valid option is currently
selected.
User agents are expected to render the labels in a select
in such a
manner
that
any alignment remains consistent whether the label is being displayed as part of the page or in
a
menu control.
Need to detail the expected native appearance and primitive appearance.
textarea
elementThe textarea
element is a devolvable
widget expected to render as an
'inline-block' box depicting a multiline text control.
If this
multiline text control
provides a selection, then, when the user changes the current selection, the user agent is
expected to queue
an
element
task on the user interaction task source
given the textarea
element
to fire an
event
named select at
the
element, with
the bubbles
attribute initialized to true.
The textarea
element is an element with default preferred size,
and
user agents are expected to apply the 'field-sizing'
CSS
property to
textarea
elements.
If the 'field-sizing' property on the element has a computed value
of 'content',
the intrinsic size is
determined from the text which the element shows. The text is either a
raw
value
or a
short hint specified by the
placeholder
attribute. User agents may take the
text caret size into account in the intrinsic
size.
Otherwise, its
intrinsic size is computed from textarea
effective width and
textarea
effective
height (as defined below).
The textarea effective width of a textarea
element
is size×avg + sbw, where
size is the element's character width,
avg is the average character width of the primary font of the element, in CSS
pixels, and sbw is the width of a scrollbar, in CSS
pixels. (The element's 'letter-spacing' property does not
affect the result.)
The textarea effective height of a textarea
element
is the height in
CSS
pixels of the number of lines specified the element's character height, plus the height of
a
scrollbar in
CSS
pixels.
User agents are expected to apply the 'white-space' CSS property to
textarea
elements. For historical reasons, if the element has a wrap
attribute
whose
value is an ASCII
case-insensitive match for the string "off", then the user agent is
expected to
treat the
attribute as a presentational
hint setting the element's
'white-space' property to 'pre'.
Need to detail the expected native appearance and primitive appearance.
User agents are expected to render frameset
elements as a box with the height and
width of the viewport, with a surface rendered according to the following
layout
algorithm:
The cols and rows variables are lists of zero or more pairs consisting of a number and a unit, the unit being one of percentage, relative, and absolute.
Use the rules for parsing a
list of
dimensions to parse the value of the
element's cols attribute, if there is one.
Let cols be the result, or an empty list if there is no such attribute.
Use the rules for parsing a
list of
dimensions to parse the value of the
element's rows attribute, if there is one.
Let rows be the result, or an empty list if there is no such attribute.
For any of the entries in cols or rows that have the number zero and the unit relative, change the entry's number to one.
If cols has no entries, then add a single entry consisting of the value 1 and the unit relative to cols.
If rows has no entries, then add a single entry consisting of the value 1 and the unit relative to rows.
Invoke the algorithm defined below to convert
a
list of
dimensions to a list of pixel
values using cols as the input list, and the width of the surface
that the
frameset is being
rendered
into,
in CSS pixels, as the
input dimension. Let sized cols be the resulting list.
Invoke the algorithm defined below to convert
a
list of
dimensions to a list of pixel
values using rows as the input list, and the height of the surface
that the
frameset is being
rendered
into,
in CSS pixels, as the
input dimension. Let sized rows be the resulting list.
Split the surface into a grid of w×h rectangles, where w is the number of entries in sized cols and h is the number of entries in sized rows.
Size the columns so that each column in the grid is as many CSS pixels wide as the corresponding entry in the sized cols list.
Size the rows so that each row in the grid is as many CSS pixels high as the corresponding entry in the sized rows list.
Let children be the list of frame and frameset elements
that are children
of the
frameset element
for which the algorithm was invoked.
For each row of the grid of rectangles created in the previous step, from top to bottom, run these substeps:
For each rectangle in the row, from left to right, run these substeps:
If there are any elements left in children, take the first element in the list, and assign it to the rectangle.
If this is a frameset
element,
then recurse the entire frameset
layout algorithm for that frameset
element,
with the rectangle as the
surface.
Otherwise, it is a frame
element; render its content
navigable, positioned and sized to fit the rectangle.
If there are any elements left in children, remove the first element from children.
If the frameset
element has a border,
draw an outer set
of
borders
around the rectangles, using the element's frame border color.
For each rectangle, if there is an element assigned to that rectangle, and that element has a border, draw an inner set of borders around that rectangle, using the element's frame border color.
For each (visible) border that does not abut a rectangle that is assigned a
frame element with a
noresize
attribute (including rectangles in further nested frameset elements),
the
user
agent is expected to allow the user to move the border, resizing the rectangles within,
keeping
the proportions of any nested frameset grids.
A frameset or
frame element has
a
border if the
following algorithm returns true:
If the element has a frameborder attribute whose value is not the
empty string and whose first character is either a U+0031 DIGIT ONE (1)
character, a
U+0079
LATIN SMALL LETTER Y character (y), or a U+0059 LATIN CAPITAL LETTER Y character
(Y),
then
return true.
Otherwise, if the element has a frameborder attribute, return
false.
Otherwise, if the element has a parent element that is a frameset
element,
then return true if that element has a border, and false if it
does
not.
Otherwise, return true.
The frame border color of a
frameset or frame element is the color
obtained from
the following
algorithm:
If the element has a bordercolor attribute, and applying the
rules for
parsing a
legacy
color value to that attribute's value does not result
in an error, then return the color so obtained.
Otherwise, if the element has a parent element that is a frameset
element,
then return the frame
border color of that element.
Otherwise, return gray.
The algorithm to convert a list of dimensions to a list of pixel values consists of the following steps:
Let input list be the list of numbers and units passed to the algorithm.
Let output list be a list of numbers the same length as input list, all zero.
Entries in output list correspond to the entries in input list that have the same position.
Let input dimension be the size passed to the algorithm.
Let count percentage be the number of entries in input list whose unit is percentage.
Let total percentage be the sum of all the numbers in input list whose unit is percentage.
Let count relative be the number of entries in input list whose unit is relative.
Let total relative be the sum of all the numbers in input list whose unit is relative.
Let count absolute be the number of entries in input list whose unit is absolute.
Let total absolute be the sum of all the numbers in input list whose unit is absolute.
Let remaining space be the value of input dimension.
If total absolute is greater than remaining space, then for each entry in input list whose unit is absolute, set the corresponding value in output list to the number of the entry in input list multiplied by remaining space and divided by total absolute. Then, set remaining space to zero.
Otherwise, for each entry in input list whose unit is absolute, set the corresponding value in output list to the number of the entry in input list. Then, decrement remaining space by total absolute.
If total percentage multiplied by the input dimension and divided by 100 is greater than remaining space, then for each entry in input list whose unit is percentage, set the corresponding value in output list to the number of the entry in input list multiplied by remaining space and divided by total percentage. Then, set remaining space to zero.
Otherwise, for each entry in input list whose unit is percentage, set the corresponding value in output list to the number of the entry in input list multiplied by the input dimension and divided by 100. Then, decrement remaining space by total percentage multiplied by the input dimension and divided by 100.
For each entry in input list whose unit is relative, set the corresponding value in output list to the number of the entry in input list multiplied by remaining space and divided by total relative.
Return output list.
User agents working with integer values for frame widths (as opposed to user agents that can lay frames out with subpixel accuracy) are expected to distribute the remainder first to the last entry whose unit is relative, then equally (not proportionally) to each entry whose unit is percentage, then equally (not proportionally) to each entry whose unit is absolute, and finally, failing all else, to the last entry.
The contents of a frame element
that does
not
have a frameset parent
are expected to be rendered as transparent
black; the user agent is expected to not
render its content
navigable
in this
case, and its content
navigable is
expected to have a viewport with zero
width and zero height.
User agents are expected to allow the user to control aspects of hyperlink activation and form submission, such as which navigable is to be used for the subsequent navigation.
User agents are expected to allow users to discover the destination of hyperlinks and of forms before triggering their navigation.
User agents are expected to inform the user of whether a hyperlink includes hyperlink auditing, and to let them know at a minimum which domains will be contacted as part of such auditing.
User agents may allow users to navigate
navigables to the URLs indicated by
the
cite attributes on q,
blockquote,
ins,
and del
elements.
User agents may surface hyperlinks
created by
link
elements in their user interface, as discussed previously.
title attributeUser agents are expected to expose the advisory information of elements upon user request, and to make the user aware of the presence of such information.
On interactive graphical systems where the user can use a pointing device, this could take the form of a tooltip. When the user is unable to use a pointing device, then the user agent is expected to make the content available in some other fashion, e.g. by making the element a focusable area and always displaying the advisory information of the currently focused element, or by showing the advisory information of the elements under the user's finger on a touch device as the user pans around the screen.
U+000A LINE FEED (LF) characters are expected to cause line breaks in the tooltip; U+0009 CHARACTER TABULATION (tab) characters are expected to render as a nonzero horizontal shift that lines up the next glyph with the next tab stop, with tab stops occurring at points that are multiples of 8 times the width of a U+0020 SPACE character.
For example, a visual user agent could make elements with a title attribute focusable, and could make
any focused element with a title attribute
show its tooltip under the element while the element has focus. This would allow a user to
tab
around the document to find all the advisory text.
As another example, a screen reader could provide an audio cue when reading an element with a tooltip, with an associated key to read the last tooltip for which a cue was played.
The current text editing caret (i.e. the active range, if it is empty and in an editing host), if any, is expected to act like an inline replaced element with the vertical dimensions of the caret and with zero width for the purposes of the CSS rendering model.
This means that even an empty block can have the caret inside it, and that when the caret is in such an element, it prevents margins from collapsing through the element.
User agents are expected to honor the Unicode semantics of text that is exposed in user interfaces, for example supporting the bidirectional algorithm in text shown in dialogs, title bars, popup menus, and tooltips. Text from the contents of elements is expected to be rendered in a manner that honors the directionality of the element from which the text was obtained. Text from attributes is expected to be rendered in a manner that honours the directionality of the attribute.
Consider the following markup, which has Hebrew text asking for a programming language, the languages being text for which a left-to-right direction is important given the punctuation in some of their names:
< p dir = "rtl" lang = "he" >
< label >
בחר שפת תכנות:
< select >
< option dir = "ltr" > C++</ option >
< option dir = "ltr" > C#</ option >
< option dir = "ltr" > FreePascal</ option >
< option dir = "ltr" > F#</ option >
</ select >
</ label >
</ p >
If the select
element was rendered as a drop down box, a correct rendering would
ensure that the punctuation was the same both in the drop down, and in the box showing the
current selection.

The directionality of attributes depends on the attribute and on the element's dir
attribute,
as the
following example demonstrates. Consider this
markup:
< table >
< tr >
< th abbr = "(א" dir = ltr > A
< th abbr = "(א" dir = rtl > A
< th abbr = "(א" dir = auto > A
</ table >
If the abbr
attributes are rendered, e.g. in a tooltip or
other user interface, the first will have a left parenthesis (because the direction is
'ltr'),
the second will have a right parenthesis (because the direction is 'rtl'), and the third
will
have a right parenthesis (because the direction is determined from the attribute
value
to be 'rtl').
However, if instead the attribute was not a directionality-capable attribute, the results would be different:
< table >
< tr >
< th data-abbr = "(א" dir = ltr > A
< th data-abbr = "(א" dir = rtl > A
< th data-abbr = "(א" dir = auto > A
</ table >
In this case, if the user agent were to expose the data-abbr attribute
in the user interface (e.g. in a debugging environment), the last case would be rendered
with a
left parenthesis, because the direction would be determined from the element's
contents.
A string provided by a script (e.g. the argument to window.alert())
is
expected to be treated as an independent set of one or
more bidirectional algorithm paragraphs when displayed, as defined by the bidirectional
algorithm,
including, for instance, supporting the paragraph-breaking behavior of U+000A LINE FEED (LF)
characters. For the purposes of determining the paragraph level of such text in the
bidirectional
algorithm, this specification does not provide a higher-level override of rules P2 and
P3. [BIDI]
When necessary, authors can enforce a particular direction for a given paragraph by starting it with the Unicode U+200E LEFT-TO-RIGHT MARK or U+200F RIGHT-TO-LEFT MARK characters.
Thus, the following script:
alert( '\u05DC\u05DE\u05D3 HTML \u05D4\u05D9\u05D5\u05DD!' )
...would always result in a message reading "למד LMTH היום!" (not "דמל HTML םויה!"), regardless of the language of the user agent interface or the direction of the page or any of its elements.
For a more complex example, consider the following script:
/* Warning: this script does not handle right-to-left scripts correctly */
var s;
if ( s = prompt( 'What is your name?' )) {
alert( s + '! Ok, Fred, ' + s + ', and Wilma will get the car.' );
}
When the user enters "Kitty", the user agent would alert "Kitty! Ok, Fred, Kitty, and Wilma will get the car.". However, if the user enters "لا أفهم", then the bidirectional algorithm will determine that the direction of the paragraph is right-to-left, and so the output will be the following unintended mess: "لا أفهم! derF ,kO, لا أفهم, rac eht teg lliw amliW dna."
To force an alert that starts with user-provided text (or other text of unknown directionality) to render left-to-right, the string can be prefixed with a U+200E LEFT-TO-RIGHT MARK character:
var s;
if ( s = prompt( 'What is your name?' )) {
alert( ' \u200E ' + s + '! Ok, Fred, ' + s + ', and Wilma will get the car.' );
}
User agents are expected to allow the user to request the opportunity to obtain a
physical
form (or a representation of a physical form) of a Document. For example,
selecting the option to print a page or convert it to PDF format. [PDF]
When the user actually obtains a
physical
form (or
a representation of a physical form) of a Document,
the user agent is expected to
create a new rendering of the Document for
the
print media.
HTML user agents may, in certain circumstances, find themselves rendering non-HTML documents that use vocabularies for which they lack any built-in knowledge. This section provides for a way for user agents to handle such documents in a somewhat useful manner.
While a Document is an unstyled document,
the user
agent is
expected
to render an
unstyled
document view.
A Document is an unstyled document while it matches the following
conditions:
Document has no
author
style
sheets (whether referenced by HTTP headers, processing instructions, elements like link,
inline
elements
like style,
or any
other mechanism).
Document
have any presentational
hints.
Document
have any style
attributes.
Document
are in any of the following namespaces: HTML
namespace,
SVG namespace, MathML
namespace
Document has no
focusable area (e.g.
from
XLink) other
than the viewport.
Document has no
hyperlinks (e.g. from XLink).
Window
object
with
this Document as its
associated
Document.
Document have any
registered
event
listeners.
An unstyled document view is one where the DOM is not
rendered
according
to CSS
(which would, since there are no applicable styles in this context, just result in a wall of
text), but is instead rendered in a manner that is useful for a developer. This could consist of
just showing the Document
object's
source, maybe with syntax highlighting, or it
could consist of displaying just the DOM tree, or simply a message saying that the page is not a
styled document.
If a Document
stops
being an
unstyled document,
then the
conditions above stop applying, and thus a user agent following these requirements will switch
to
using the regular CSS rendering.
Features listed in this section will trigger warnings in conformance checkers.
Authors should not specify a border
attribute on
an
img
element. If
the attribute is present, its value must be the string "0". CSS should be used
instead.
Authors should not specify a charset
attribute on a
script
element. If the attribute is present, its value must be an ASCII
case-insensitive match for "utf-8". (This has no effect in a
document that conforms to the requirements elsewhere in this standard of being encoded as
UTF-8.)
Authors should not specify a language
attribute on a
script
element. If the attribute is present, its value must be an ASCII
case-insensitive match for the string "JavaScript" and either the
type
attribute
must be omitted or its value must be an
ASCII
case-insensitive match for the string "text/javascript".
The attribute should be entirely omitted instead (with the value "JavaScript", it
has no
effect),
or replaced with use of the type
attribute.
Authors should not specify a value for the type
attribute on script
elements that is the empty string or a JavaScript MIME type
essence match. Instead, they should omit the attribute, which has the same effect.
Authors should not specify a type
attribute on a
style
element.
If the attribute is present, its value must be an ASCII
case-insensitive match for "text/css".
Authors should not specify the name
attribute on
a
elements. If
the
attribute is present, its value must not be the empty string and
must neither be equal to the value of any of the IDs in the
element's tree other than the
element's own ID, if
any, nor be equal to the value of any of the other name
attributes on a
elements in the element's tree. If this
attribute is
present and the element has an ID, then the
attribute's
value
must be equal to the element's ID. In
earlier
versions of
the
language, this attribute was intended as a way to specify possible targets for fragments
in URLs. The id
attribute
should be used instead.
Authors should not, but may despite requirements to the contrary elsewhere in this
specification, specify the maxlength
and size
attributes on input
elements
whose type
attributes are in the Number state. One valid
reason
for
using these attributes
regardless is to help legacy user agents that do not support input
elements
with
type="number" to still render the text control with a useful width.
To ease the transition from HTML4 Transitional documents to the language defined in this specification, and to discourage certain features that are only allowed in very few circumstances, conformance checkers must warn the user when the following features are used in a document. These are generally old obsolete features that have no effect, and are allowed only to distinguish between likely mistakes (regular conformance errors) and mere vestigial markup or unusual and discouraged practices (these warnings).
The following features must be categorized as described above:
The presence of a border
attribute on an
img
element if its value is the string "0".
The presence of a charset
attribute on a
script
element if its value is an ASCII case-insensitive match for
"utf-8".
The presence of a language
attribute on a
script
element if its value is an ASCII case-insensitive match for the
string "JavaScript" and if there is no type
attribute or there is and its value is an ASCII
case-insensitive match for the string "text/javascript".
The presence of a type
attribute on a
script
element if its value is a JavaScript MIME type essence
match.
The presence of a type
attribute on a
style
element if its value is an ASCII case-insensitive match for
"text/css".
The presence of a name
attribute on an a
element, if its value is not the empty string.
The presence of a maxlength
attribute on an
input
element whose type
attribute is in the
Number
state.
The presence of a size
attribute on an
input
element whose type
attribute is in the
Number
state.
Conformance checkers must distinguish between pages that have no conformance errors and have none of these obsolete features, and pages that have no conformance errors but do have some of these obsolete features.
For example, a validator could report some pages as "Valid HTML" and others as "Valid HTML with warnings".
Elements in the following list are entirely obsolete, and must not be used by authors:
applet
acronym
Use abbr
instead.
bgsound
Use audio
instead.
dir
Use ul
instead.
frame
frameset
noframes
Either use iframe
and CSS
instead, or use server-side includes to generate complete pages with the various
invariant parts
merged
in.
isindex
Use an explicit form
and text
control
combination instead.
keygen
For enterprise device management use cases, use native on-device management capabilities.
For certificate enrollment use cases, use the Web Cryptography API to generate a keypair for the certificate, and then export the certificate and key to allow the user to install them manually. [WEBCRYPTO]
listing
menuitem
To implement a custom context menu, use script to handle the contextmenu
event.
nextid
Use GUIDs instead.
noembed
param
Use the data
attribute of the object
element to set the
URL of the external resource.
plaintext
Use the "text/plain"
MIME
type instead.
rb
rtc
Providing the ruby base directly inside the ruby
element or
using nested
ruby
elements
is sufficient.
strike
Use del
instead if
the element is marking an edit, otherwise use s
instead.
xmp
Use pre
and code
instead, and
escape "<" and "&" characters as
"<" and
"&" respectively.
basefont
big
blink
center
font
marquee
multicol
nobr
spacer
tt
Use appropriate elements or CSS instead.
Where the tt element would
have been
used for
marking up keyboard input,
consider the kbd
element; for variables, consider the var
element;
for
computer code, consider the code
element; and
for computer output, consider the
samp
element.
Similarly, if the big
element is
being used
to denote a heading, consider using
the h1
element; if it is being used for marking up important passages, consider the
strong
element; and if it is being used for highlighting text for reference
purposes, consider the mark
element.
See also the text-level semantics usage summary for more suggestions with examples.
The following attributes are obsolete (though the elements are still part of the language), and must not be used by authors:
charset
on a
elements
charset on
link
elements
Use an HTTP `Content-Type`
header on the linked resource instead.
charset on
script
elements (except as noted in the previous section)
Omit the attribute. Both documents and scripts are required to use UTF-8, so
it is redundant to specify it on the script
element since it inherits from the
document.
coords on
a
elements
shape on
a
elements
methods
on a
elements
methods on
link
elements
Use the HTTP OPTIONS feature instead.
name on
a
elements (except
as noted
in the previous section)
name on
embed
elements
name on
img
elements
name on
option
elements
Use the id
attribute instead.
rev on a elements
rev on
link
elements
Use the rel
attribute instead, with an opposite term. (For example, instead of
rev="made", use rel="author".)
urn on a elements
urn on
link
elements
Specify the preferred persistent identifier using the href
attribute instead.
accept on
form
elements
Use the accept
attribute directly on the input
elements
instead.
hreflang
on area
elements
type
on area
elements
These attributes do not do anything useful, and for historical reasons there are no
corresponding IDL attributes on area
elements.
Omit them altogether.
nohref on
area
elements
Omitting the href
attribute is sufficient; the nohref
attribute is
unnecessary. Omit it altogether.
profile on
head
elements
Unnecessary. Omit it altogether.
manifest
on html
elements
Use service workers instead. [SW]
version on
html
elements
Unnecessary. Omit it altogether.
ismap on
input
elements
Unnecessary. Omit it altogether. All input
elements
with a type
attribute in the Image
Button state are processed as server-side image maps.
usemap on
input
elements
usemap
on object
elements
Use the img
element for image maps.
longdesc
on
iframe
elements
longdesc on
img
elements
Use a regular a
element to link to the
description, or (in the case of images) use an image
map to provide a link from the image to the image's
description.
lowsrc on
img
elements
Use a progressive JPEG image (given in the src
attribute),
instead of using two separate images.
target on
link
elements
Unnecessary. Omit it altogether.
type
on menu
elements
To implement a custom context menu, use script to handle the contextmenu
event. For toolbar menus, omit the
attribute.
label on
menu
elements
contextmenu on all
elements
onshow on all elements
To implement a custom context menu, use script to handle the contextmenu
event.
scheme on
meta
elements
Use only one scheme per field, or make the scheme declaration part of the value.
archive on
object
elements
classid on
object
elements
code on
object
elements
codebase
on
object
elements
codetype
on
object
elements
declare on
object
elements
Repeat the object
element completely each time the resource is to be reused.
standby on
object
elements
Optimize the linked resource so that it loads quickly or, at least, incrementally.
typemustmatch on object
elements
Avoid using object
elements with untrusted resources.
language
on
script
elements
(except as noted in the previous section)
Omit the attribute for JavaScript; for data
blocks, use
the type
attribute instead.
event on
script
elements
for on
script
elements
Use DOM events mechanisms to register event listeners. [DOM]
type on
style
elements
(except as noted in the previous section)
Omit the attribute for CSS; for data
blocks, use
script
as
the container instead of style.
datapagesize on table
elements
Unnecessary. Omit it altogether.
summary
on table
elements
Use one of the techniques for describing
tables given in the table
section
instead.
abbr on
td
elements
Use text that begins in an unambiguous and terse manner, and include any more elaborate
text
after that.
The title
attribute
can also
be useful in including more detailed text, so that the cell's contents can be made
terse. If
it's a
heading, use th
(which has an abbr
attribute).
axis
on
td and
th
elements
scope on
td
elements
Use th
elements for
heading cells.
datasrc on a, button,
div,
frame, iframe,
img,
input,
label,
legend,
marquee,
object,
option,
select,
span,
table,
and
textarea
elements
datafld on a, button,
div,
fieldset,
frame, iframe,
img,
input,
label,
legend,
marquee,
object,
select,
span,
and
textarea
elements
dataformatas on
button,
div,
input,
label,
legend,
marquee,
object,
option,
select,
span,
and
table
elements
Use script and a mechanism such as XMLHttpRequest
to populate the page dynamically. [XHR]
dropzone on all elements
Use script to handle the dragenter
and
dragover
events instead.
alink on
body
elements
bgcolor on
body
elements
bottommargin
on body
elements
leftmargin
on
body
elements
link
on body
elements
marginheight
on body
elements
marginwidth on
body
elements
rightmargin on
body
elements
text
on body
elements
topmargin on
body
elements
vlink on
body
elements
clear on
br
elements
align
on caption
elements
align
on col
elements
char on
col
elements
charoff on
col
elements
valign on
col
elements
width
on col
elements
align
on div
elements
compact on
dl
elements
align on
embed
elements
hspace on
embed
elements
vspace on
embed
elements
align on
hr
elements
color on
hr
elements
noshade on
hr
elements
size on
hr
elements
width on
hr
elements
align
on
h1—h6
elements
align on
iframe
elements
allowtransparency on iframe
elements
frameborder on iframe
elements
framespacing on iframe
elements
hspace
on iframe
elements
marginheight on iframe
elements
marginwidth on iframe
elements
scrolling on
iframe
elements
vspace
on iframe
elements
align on
input
elements
border on
input
elements
hspace on
input
elements
vspace on
input
elements
align
on img
elements
border on
img
elements
(except as
noted in the previous section)
hspace on
img
elements
vspace on
img
elements
align on
legend
elements
type on
li
elements
compact on
menu
elements
align on
object
elements
border
on object
elements
hspace
on object
elements
vspace
on object
elements
compact on
ol
elements
align on
p elements
width
on pre
elements
align on
table
elements
bgcolor
on table
elements
border on
table
elements
bordercolor
on table
elements
cellpadding
on table
elements
cellspacing
on table
elements
frame on
table
elements
height on
table
elements
rules on
table
elements
width on
table
elements
align on
tbody,
thead,
and
tfoot
elements
char on
tbody,
thead,
and tfoot
elements
charoff
on tbody,
thead,
and tfoot
elements
height on
thead,
tbody,
and tfoot
elements
valign on
tbody,
thead,
and tfoot
elements
align on
td and
th
elements
bgcolor
on td
and th
elements
char
on
td and
th
elements
charoff
on td
and th
elements
height on
td and
th
elements
nowrap on
td and
th
elements
valign on
td and
th
elements
width on
td and
th
elements
align on
tr
elements
bgcolor on
tr
elements
char on
tr
elements
charoff on
tr
elements
height
on tr
elements
valign
on tr
elements
compact on
ul
elements
type on
ul
elements
background on body,
table,
thead,
tbody,
tfoot,
tr,
td,
and th
elements
Use CSS instead.
marquee
elementThe marquee
element is a
presentational element that animates content. CSS
transitions and animations are a more appropriate mechanism. [CSSANIMATIONS]
[CSSTRANSITIONS]
The marquee
element
must implement the HTMLMarqueeElement
interface.
[Exposed =Window ]
interface HTMLMarqueeElement : HTMLElement {
[HTMLConstructor ] constructor ();
[CEReactions ] attribute DOMString behavior ;
[CEReactions ] attribute DOMString bgColor ;
[CEReactions ] attribute DOMString direction ;
[CEReactions ] attribute DOMString height ;
[CEReactions ] attribute unsigned long hspace ;
[CEReactions ] attribute long loop ;
[CEReactions ] attribute unsigned long scrollAmount ;
[CEReactions ] attribute unsigned long scrollDelay ;
[CEReactions ] attribute boolean trueSpeed ;
[CEReactions ] attribute unsigned long vspace ;
[CEReactions ] attribute DOMString width ;
undefined start ();
undefined stop ();
};
A marquee
element can
be turned on or turned off.
When it
is
created, it is turned
on.
When the start() method is called, the marquee
element
must be turned on.
When the stop()
method is called, the marquee
element
must be turned off.
The behavior
content attribute on marquee
elements is an
enumerated
attribute with
the following keywords and states (all non-conforming):
| Keyword | State |
|---|---|
scroll
| scroll |
slide
| slide |
alternate
| alternate |
The attribute's missing value default and invalid value default are both the scroll state.
The direction
content attribute on marquee
elements is an enumerated
attribute with the following keywords and states (all
non-conforming):
| Keyword | State |
|---|---|
left
| left |
right
| right |
up
| up |
down
| down |
The attribute's missing value default and invalid value default are both the left state.
The truespeed
content attribute on marquee
elements is a boolean
attribute.
A marquee
element has
a marquee scroll interval, which is obtained as
follows:
If the element has a scrolldelay attribute,
and parsing its value using the rules for parsing
non-negative
integers does not
return an error, then let delay be the parsed value. Otherwise, let
delay
be 85.
If the element does not have a truespeed
attribute, and the delay value is less than 60, then let delay be
60
instead.
The marquee scroll interval is delay, interpreted in milliseconds.
A marquee
element has
a marquee scroll distance, which, if the element
has a scrollamount attribute, and
parsing its value using the rules for parsing
non-negative
integers
does not return
an error, is the parsed value interpreted in CSS pixels, and otherwise
is 6 CSS
pixels.
A marquee
element has
a marquee loop count, which, if the element has a
loop
attribute, and
parsing its value using the rules for parsing integers does not
return an
error or
a
number less than 1, is the parsed value, and otherwise is −1.
The loop
IDL attribute, on getting, must return the element's marquee loop count; and on
setting, if the new value is different than the element's marquee loop count and
either greater than zero or equal to −1, must set the element's loop content
attribute
(adding it if necessary) to the
valid integer that represents
the new
value.
(Other values are ignored.)
A marquee
element
also has a marquee current loop index, which is zero
when the element is created.
The rendering layer will occasionally increment the marquee current loop index, which must cause the following steps to be run:
If the marquee loop count is −1, then return.
Increment the marquee current loop index by one.
If the marquee
current loop index is now greater than or equal to the
element's marquee loop
count, turn
off
the
marquee
element.
The behavior, direction, height,
hspace,
vspace,
and width
IDL attributes must
reflect the respective content attributes of
the
same name.
The bgColor IDL attribute must reflect the
bgcolor content attribute.
The scrollAmount IDL attribute must
reflect the scrollamount
content attribute. The default
value is
6.
The scrollDelay IDL attribute must reflect
the scrolldelay content attribute. The
default value is 85.
The trueSpeed IDL attribute must reflect the
truespeed
content attribute.
The frameset element acts as the body element in
documents that use frames.
The frameset element must implement the
HTMLFrameSetElement
interface.
[Exposed =Window ]
interface HTMLFrameSetElement : HTMLElement {
[HTMLConstructor ] constructor ();
[CEReactions ] attribute DOMString cols ;
[CEReactions ] attribute DOMString rows ;
};
HTMLFrameSetElement includes WindowEventHandlers ;
The cols
and rows
IDL attributes of the frameset element
must reflect the respective
content attributes of the same name.
The frameset element exposes as event
handler
content
attributes a
number of the event handlers of the Window object. It also mirrors their
event handler IDL
attributes.
The event handlers of the Window object named by the
Window-reflecting
body
element event
handler set, exposed on the
frameset element, replace the generic event handlers with the same names
normally supported by HTML elements.
The frame element has a content navigable similar
to the iframe element,
but
rendered
within a frameset element.
The frame HTML element insertion steps, given
insertedNode, are:
If insertedNode is not in a document tree, then return.
If insertedNode's root's browsing context is null, then return.
Create a new child navigable for insertedNode.
Process the
frame attributes for insertedNode, with
initialInsertion set to true.
The frame HTML element removing steps, given
removedNode,
are to destroy a child
navigable
given removedNode.
Whenever a frame element with a non-null content navigable has its
src attribute set, changed, or removed, the user
agent must process the
frame attributes.
To process the frame attributes for an
element
element, with
an optional boolean initialInsertion:
Let url be the result of running the shared
attribute
processing steps
for iframe and frame elements given element
and
initialInsertion.
If url is null, then return.
If url matches
about:blank and
initialInsertion is true, then:
Fire an
event named load at
element.
Return.
Navigate an
iframe or frame given
element, url, and the empty string.
The frame element potentially
delays the load event.
The frame element must implement the HTMLFrameElement interface.
[Exposed =Window ]
interface HTMLFrameElement : HTMLElement {
[HTMLConstructor ] constructor ();
[CEReactions ] attribute DOMString name ;
[CEReactions ] attribute DOMString scrolling ;
[CEReactions ] attribute USVString src ;
[CEReactions ] attribute DOMString frameBorder ;
[CEReactions ] attribute USVString longDesc ;
[CEReactions ] attribute boolean noResize ;
readonly attribute Document ? contentDocument ;
readonly attribute WindowProxy ? contentWindow ;
[CEReactions ] attribute [LegacyNullToEmptyString ] DOMString marginHeight ;
[CEReactions ] attribute [LegacyNullToEmptyString ] DOMString marginWidth ;
};
The name,
scrolling,
and
src IDL
attributes
of the frame element must reflect the respective content attributes of
the same name. For the purposes of reflection, the frame
element's src content attribute is defined as containing a
URL.
The frameBorder IDL attribute of the frame
element must reflect the element's
frameborder
content
attribute.
The longDesc
IDL attribute of the frame element
must reflect the element's longdesc
content
attribute,
which for the purposes of
reflection is defined as containing a URL.
The noResize
IDL attribute of the frame element
must reflect the element's noresize
content
attribute.
The marginHeight IDL attribute of the frame
element must reflect the element's
marginheight
content
attribute.
The marginWidth IDL attribute of the frame
element must reflect the element's
marginwidth
content
attribute.
The contentDocument getter steps are to return
this's content
document.
The contentWindow getter steps are to return
this's content window.
User agents must treat acronym
elements in a manner
equivalent to abbr
elements
in terms of semantics and
for purposes of rendering.
partial interface HTMLAnchorElement {
[CEReactions ] attribute DOMString coords ;
[CEReactions ] attribute DOMString charset ;
[CEReactions ] attribute DOMString name ;
[CEReactions ] attribute DOMString rev ;
[CEReactions ] attribute DOMString shape ;
};
The coords,
charset,
name, rev, and shape IDL
attributes of the
a
element
must reflect the respective
content
attributes
of the same
name.
partial interface HTMLAreaElement {
[CEReactions ] attribute boolean noHref ;
};
The noHref
IDL
attribute of the area
element
must reflect the element's
nohref
content
attribute.
partial interface HTMLBodyElement {
[CEReactions ] attribute [LegacyNullToEmptyString ] DOMString text ;
[CEReactions ] attribute [LegacyNullToEmptyString ] DOMString link ;
[CEReactions ] attribute [LegacyNullToEmptyString ] DOMString vLink ;
[CEReactions ] attribute [LegacyNullToEmptyString ] DOMString aLink ;
[CEReactions ] attribute [LegacyNullToEmptyString ] DOMString bgColor ;
[CEReactions ] attribute DOMString background ;
};
The text
IDL
attribute of the body
element
must reflect the element's
text
content
attribute.
The link
IDL
attribute of the body
element
must reflect the element's
link
content
attribute.
The aLink
IDL
attribute of the body
element
must reflect the element's
alink
content
attribute.
The vLink
IDL
attribute of the body
element
must reflect the element's
vlink
content
attribute.
The bgColor
IDL attribute of the body
element
must reflect the element's
bgcolor
content attribute.
The background IDL attribute of the body
element must reflect the
element's
background
content attribute. (The background
content is not
defined to contain a URL, despite rules
regarding
its handling in the Rendering
section above.)
partial interface HTMLBRElement {
[CEReactions ] attribute DOMString clear ;
};
The clear IDL
attribute of the br
element
must reflect the content
attribute
of the
same name.
partial interface HTMLTableCaptionElement {
[CEReactions ] attribute DOMString align ;
};
The align IDL attribute of the caption
element
must reflect the content
attribute of the
same name.
partial interface HTMLTableColElement {
[CEReactions ] attribute DOMString align ;
[CEReactions ] attribute DOMString ch ;
[CEReactions ] attribute DOMString chOff ;
[CEReactions ] attribute DOMString vAlign ;
[CEReactions ] attribute DOMString width ;
};
The align
and width
IDL
attributes of the col
element must
reflect the respective
content
attributes of the same name.
The ch IDL
attribute of the col
element
must reflect the
element's char
content
attribute.
The chOff
IDL attribute of the col
element
must reflect the
element's charoff
content
attribute.
The vAlign
IDL attribute of the col
element
must reflect the
element's valign
content
attribute.
User agents must treat dir
elements in a
manner equivalent to ul
elements in terms of semantics and for purposes of rendering.
The dir element must
implement
the
HTMLDirectoryElement
interface.
[Exposed =Window ]
interface HTMLDirectoryElement : HTMLElement {
[HTMLConstructor ] constructor ();
[CEReactions ] attribute boolean compact ;
};
The compact
IDL attribute of the dir
element must
reflect the content
attribute of
the same
name.
partial interface HTMLDivElement {
[CEReactions ] attribute DOMString align ;
};
The align
IDL
attribute of the div
element must
reflect the content
attribute of
the
same name.
partial interface HTMLDListElement {
[CEReactions ] attribute boolean compact ;
};
The compact
IDL attribute of the dl
element
must reflect the content
attribute of
the same name.
partial interface HTMLEmbedElement {
[CEReactions ] attribute DOMString align ;
[CEReactions ] attribute DOMString name ;
};
The name
and
align
IDL
attributes of the embed
element
must reflect the
respective
content
attributes of the same name.
The font element must
implement the
HTMLFontElement
interface.
[Exposed =Window ]
interface HTMLFontElement : HTMLElement {
[HTMLConstructor ] constructor ();
[CEReactions ] attribute [LegacyNullToEmptyString ] DOMString color ;
[CEReactions ] attribute DOMString face ;
[CEReactions ] attribute DOMString size ;
};
The color,
face, and
size IDL
attributes
of the
font element must
reflect the respective
content
attributes of the same
name.
partial interface HTMLHeadingElement {
[CEReactions ] attribute DOMString align ;
};
The align
IDL
attribute of the h1–h6
elements must reflect the
content attribute of the same name.
The profile IDL attribute on head
elements
(with
the HTMLHeadElement
interface) is intentionally omitted. Unless so required by another applicable
specification,
implementations
would therefore not support this attribute. (It is mentioned here as it was defined in a
previous
version of DOM.)
partial interface HTMLHRElement {
[CEReactions ] attribute DOMString align ;
[CEReactions ] attribute DOMString color ;
[CEReactions ] attribute boolean noShade ;
[CEReactions ] attribute DOMString size ;
[CEReactions ] attribute DOMString width ;
};
The align,
color, size, and width
IDL
attributes
of the
hr
element must
reflect the respective
content
attributes
of the same
name.
The noShade
IDL
attribute of the hr
element must
reflect the element's
noshade
content
attribute.
partial interface HTMLHtmlElement {
[CEReactions ] attribute DOMString version ;
};
The version
IDL attribute of the html
element
must reflect the content
attribute of
the same name.
partial interface HTMLIFrameElement {
[CEReactions ] attribute DOMString align ;
[CEReactions ] attribute DOMString scrolling ;
[CEReactions ] attribute DOMString frameBorder ;
[CEReactions ] attribute USVString longDesc ;
[CEReactions ] attribute [LegacyNullToEmptyString ] DOMString marginHeight ;
[CEReactions ] attribute [LegacyNullToEmptyString ] DOMString marginWidth ;
};
The align
and scrolling IDL attributes of the iframe
element must reflect the
respective
content attributes of the same name.
The frameBorder IDL attribute of the iframe
element must reflect the
element's frameborder
content attribute.
The longDesc IDL attribute of the iframe
element must reflect the
element's longdesc
content attribute, which for the purposes of
reflection is defined as containing a URL.
The marginHeight IDL attribute of the
iframe
element must reflect the
element's marginheight
content attribute.
The marginWidth IDL attribute of the iframe
element must reflect the
element's marginwidth
content attribute.
partial interface HTMLImageElement {
[CEReactions ] attribute DOMString name ;
[CEReactions ] attribute USVString lowsrc ;
[CEReactions ] attribute DOMString align ;
[CEReactions ] attribute unsigned long hspace ;
[CEReactions ] attribute unsigned long vspace ;
[CEReactions ] attribute USVString longDesc ;
[CEReactions ] attribute [LegacyNullToEmptyString ] DOMString border ;
};
The name,
align,
border,
hspace,
and vspace
IDL
attributes of the
img
element
must reflect the
respective
content
attributes of the same
name.
The longDesc
IDL attribute of the img
element
must reflect the
element's longdesc
content attribute, which for the purposes of reflection
is defined as containing a URL.
The lowsrc
IDL
attribute of the img
element
must reflect the
element's lowsrc
content
attribute, which for the purposes of reflection is
defined as containing a URL.
partial interface HTMLInputElement {
[CEReactions ] attribute DOMString align ;
[CEReactions ] attribute DOMString useMap ;
};
The align
IDL
attribute of the input
element
must reflect the content
attribute of the
same name.
The useMap
IDL attribute of the input
element must reflect the
element's usemap
content attribute.
partial interface HTMLLegendElement {
[CEReactions ] attribute DOMString align ;
};
The align
IDL attribute of the legend
element must reflect the
content
attribute
of the same name.
partial interface HTMLLIElement {
[CEReactions ] attribute DOMString type ;
};
The type IDL
attribute of the li
element
must reflect the content
attribute of the
same name.
partial interface HTMLLinkElement {
[CEReactions ] attribute DOMString charset ;
[CEReactions ] attribute DOMString rev ;
[CEReactions ] attribute DOMString target ;
};
The charset,
rev, and
target
IDL
attributes
of the link
element must reflect the
respective
content attributes of
the same name.
User agents must treat listing
elements in a manner equivalent to pre
elements in terms of semantics and for purposes of rendering.
partial interface HTMLMenuElement {
[CEReactions ] attribute boolean compact ;
};
The compact
IDL attribute of the menu
element
must reflect the content
attribute of
the same name.
partial interface HTMLMetaElement {
[CEReactions ] attribute DOMString scheme ;
};
User agents may treat the scheme
content
attribute on the
meta
element
as an extension of the element's name
content
attribute when processing a meta
element
with a name
attribute whose value is one that the user agent
recognizes as supporting the scheme
attribute.
User agents are encouraged to ignore the scheme
attribute
and instead process the value given to the metadata name as if it had been specified for each
expected value of the scheme
attribute.
For example, if the user agent acts on meta
elements with name
attributes having the value "eGMS.subject.keyword", and knows
that the scheme
attribute is used with this metadata name,
then it could take the scheme
attribute into account,
acting as if it was an extension of the name
attribute. Thus
the following two meta
elements could be treated as two elements giving values for
two different metadata names, one consisting of a combination of "eGMS.subject.keyword" and
"LGCL", and the other consisting of a combination of "eGMS.subject.keyword" and "ORLY":
<!-- this markup is invalid -->
< meta name = "eGMS.subject.keyword" scheme = "LGCL" content = "Abandoned vehicles" >
< meta name = "eGMS.subject.keyword" scheme = "ORLY" content = "Mah car: kthxbye" >
The suggested processing of this markup, however, would be equivalent to the following:
< meta name = "eGMS.subject.keyword" content = "Abandoned vehicles" >
< meta name = "eGMS.subject.keyword" content = "Mah car: kthxbye" >
The scheme
IDL
attribute of the meta
element
must reflect the content
attribute of the
same name.
partial interface HTMLObjectElement {
[CEReactions ] attribute DOMString align ;
[CEReactions ] attribute DOMString archive ;
[CEReactions ] attribute DOMString code ;
[CEReactions ] attribute boolean declare ;
[CEReactions ] attribute unsigned long hspace ;
[CEReactions ] attribute DOMString standby ;
[CEReactions ] attribute unsigned long vspace ;
[CEReactions ] attribute DOMString codeBase ;
[CEReactions ] attribute DOMString codeType ;
[CEReactions ] attribute DOMString useMap ;
[CEReactions ] attribute [LegacyNullToEmptyString ] DOMString border ;
};
The align,
archive,
border,
code,
declare,
hspace,
standby,
and
vspace
IDL
attributes of the
object
element must reflect the
respective
content attributes of the
same name.
The codeBase IDL attribute of the object
element must reflect the
element's codebase
content attribute, which for the purposes of
reflection is defined as containing a URL.
The codeType IDL attribute of the object
element must reflect the
element's codetype
content attribute.
Support in all current engines.
The useMap
IDL attribute must reflect the
usemap
content attribute.
partial interface HTMLOListElement {
[CEReactions ] attribute boolean compact ;
};
The compact
IDL attribute of the ol
element
must reflect the content
attribute of
the same name.
partial interface HTMLParagraphElement {
[CEReactions ] attribute DOMString align ;
};
The align
IDL
attribute of the p
element must reflect the
content
attribute of the
same name.
The param element
must
implement the
HTMLParamElement
interface.
[Exposed =Window ]
interface HTMLParamElement : HTMLElement {
[HTMLConstructor ] constructor ();
[CEReactions ] attribute DOMString name ;
[CEReactions ] attribute DOMString value ;
[CEReactions ] attribute DOMString type ;
[CEReactions ] attribute DOMString valueType ;
};
The name,
value,
and type
IDL
attributes
of the param
element must
reflect the respective
content
attributes of
the same name.
The valueType IDL attribute of the param
element must reflect the
element's
valuetype content
attribute.
User agents must treat plaintext
elements in
a
manner equivalent to
pre
elements
in terms of semantics and for purposes of rendering. (The parser has
special behavior for this element, though.)
partial interface HTMLPreElement {
[CEReactions ] attribute long width ;
};
The width
IDL
attribute of the pre
element
must reflect the content
attribute of the
same name.
partial interface HTMLStyleElement {
[CEReactions ] attribute DOMString type ;
};
The type
IDL
attribute of the style
element
must reflect the
element's type
content
attribute.
partial interface HTMLScriptElement {
[CEReactions ] attribute DOMString charset ;
[CEReactions ] attribute DOMString event ;
[CEReactions ] attribute DOMString htmlFor ;
};
The charset
and event
IDL
attributes of the script
element
must reflect the
respective
content
attributes of the same name.
The htmlFor
IDL attribute of the script
element
must reflect the
element's for
content
attribute.
partial interface HTMLTableElement {
[CEReactions ] attribute DOMString align ;
[CEReactions ] attribute DOMString border ;
[CEReactions ] attribute DOMString frame ;
[CEReactions ] attribute DOMString rules ;
[CEReactions ] attribute DOMString summary ;
[CEReactions ] attribute DOMString width ;
[CEReactions ] attribute [LegacyNullToEmptyString ] DOMString bgColor ;
[CEReactions ] attribute [LegacyNullToEmptyString ] DOMString cellPadding ;
[CEReactions ] attribute [LegacyNullToEmptyString ] DOMString cellSpacing ;
};
The align,
border,
frame,
summary,
rules,
and
width,
IDL
attributes of the
table
element must reflect the
respective
content attributes of the same
name.
The bgColor
IDL attribute of the table
element must reflect the
element's bgcolor
content attribute.
The cellPadding IDL attribute of the table
element must reflect the
element's cellpadding
content attribute.
The cellSpacing IDL attribute of the table
element must reflect the
element's cellspacing
content attribute.
partial interface HTMLTableSectionElement {
[CEReactions ] attribute DOMString align ;
[CEReactions ] attribute DOMString ch ;
[CEReactions ] attribute DOMString chOff ;
[CEReactions ] attribute DOMString vAlign ;
};
The align
IDL attribute of the tbody,
thead,
and
tfoot
elements must reflect the
content
attribute of the same name.
The ch
IDL attribute of the tbody,
thead,
and tfoot
elements must
reflect the elements'
char
content
attributes.
The chOff
IDL attribute of the tbody,
thead,
and tfoot
elements must reflect the
elements' charoff
content attributes.
The vAlign IDL attribute of the tbody,
thead,
and tfoot
element must reflect the
elements' valign
content attributes.
partial interface HTMLTableCellElement {
[CEReactions ] attribute DOMString align ;
[CEReactions ] attribute DOMString axis ;
[CEReactions ] attribute DOMString height ;
[CEReactions ] attribute DOMString width ;
[CEReactions ] attribute DOMString ch ;
[CEReactions ] attribute DOMString chOff ;
[CEReactions ] attribute boolean noWrap ;
[CEReactions ] attribute DOMString vAlign ;
[CEReactions ] attribute [LegacyNullToEmptyString ] DOMString bgColor ;
};
The align,
axis,
height,
and
width
IDL
attributes of the td
and
th
elements must reflect the
respective content attributes of the same name.
The ch
IDL
attribute of the td
and
th
elements must
reflect the
elements' char
content attributes.
The chOff
IDL attribute of the td
and
th
elements must
reflect the
elements' charoff
content attributes.
The noWrap
IDL attribute of the td
and
th
elements
must reflect the
elements' nowrap
content
attributes.
The vAlign
IDL attribute of the td
and
th
elements
must reflect the
elements' valign
content
attributes.
The bgColor
IDL attribute of the td
and
th
elements
must reflect the
elements' bgcolor
content attributes.
partial interface HTMLTableRowElement {
[CEReactions ] attribute DOMString align ;
[CEReactions ] attribute DOMString ch ;
[CEReactions ] attribute DOMString chOff ;
[CEReactions ] attribute DOMString vAlign ;
[CEReactions ] attribute [LegacyNullToEmptyString ] DOMString bgColor ;
};
The align
IDL
attribute of the tr
element
must reflect the content
attribute of the
same name.
The ch IDL
attribute of the tr
element must
reflect the element's
char
content
attribute.
The chOff
IDL
attribute of the tr
element must
reflect the element's
charoff
content
attribute.
The vAlign
IDL attribute of the tr
element must
reflect the element's
valign
content
attribute.
The bgColor
IDL attribute of the tr
element must
reflect the element's
bgcolor
content
attribute.
partial interface HTMLUListElement {
[CEReactions ] attribute boolean compact ;
[CEReactions ] attribute DOMString type ;
};
The compact
and type
IDL
attributes of the ul
element must
reflect the respective
content
attributes of the same name.
User agents must treat xmp
elements in a
manner equivalent to pre
elements in terms of semantics and for purposes of rendering. (The parser has special behavior
for
this element though.)
partial interface Document {
[CEReactions ] attribute [LegacyNullToEmptyString ] DOMString fgColor ;
[CEReactions ] attribute [LegacyNullToEmptyString ] DOMString linkColor ;
[CEReactions ] attribute [LegacyNullToEmptyString ] DOMString vlinkColor ;
[CEReactions ] attribute [LegacyNullToEmptyString ] DOMString alinkColor ;
[CEReactions ] attribute [LegacyNullToEmptyString ] DOMString bgColor ;
[SameObject ] readonly attribute HTMLCollection anchors ;
[SameObject ] readonly attribute HTMLCollection applets ;
undefined clear ();
undefined captureEvents ();
undefined releaseEvents ();
[SameObject ] readonly attribute HTMLAllCollection all ;
};
The attributes of the Document
object listed in the first column of the following
table must reflect the
content
attribute
on the
body
element
with the
name given in the corresponding cell in the second column on the same row, if the
body
element is a body
element
(as opposed to a frameset
element).
When there is no body
element or if it is a
frameset
element,
the
attributes must instead return the empty string on getting and
do nothing on setting.
| IDL attribute | Content attribute |
|---|---|
fgColor
| text
|
linkColor
| link
|
vlinkColor
| vlink
|
alinkColor
| alink
|
bgColor
| bgcolor
|
The anchors
attribute must return an HTMLCollection
rooted at the Document
node,
whose filter matches only a
elements
with
name
attributes.
The applets
attribute must return an HTMLCollection
rooted at the Document
node,
whose filter matches nothing. (It exists for historical reasons.)
The clear(),
captureEvents(),
and releaseEvents() methods must do nothing.
The all
attribute
must return an HTMLAllCollection
rooted at the Document
node, whose
filter matches all elements.
partial interface Window {
undefined captureEvents ();
undefined releaseEvents ();
[Replaceable , SameObject ] readonly attribute External external ;
};
The captureEvents()
and releaseEvents()
methods must do nothing.
The external
attribute of
the Window
interface must
return
an instance of the External
interface:
[Exposed =Window ]
interface External {
undefined AddSearchProvider ();
undefined IsSearchProviderInstalled ();
};
The AddSearchProvider() and IsSearchProviderInstalled() methods
must do nothing.
text/htmlThis registration is for community review and will be submitted to the IESG for review, approval, and registration with IANA.
charset
The charset parameter may be provided to specify the
document's character
encoding,
overriding any character encoding
declarations in
the
document other than a Byte Order
Mark (BOM). The parameter's value must be an ASCII case-insensitive match for
the
string "utf-8". [ENCODING]
Entire novels have been written about the security considerations that apply to HTML documents. Many are listed in this document, to which the reader is referred for more details. Some general concerns bear mentioning here, however:
HTML is scripted language, and has a large number of APIs (some of which are described in this document). Script can expose the user to potential risks of information leakage, credential leakage, cross-site scripting attacks, cross-site request forgeries, and a host of other problems. While the designs in this specification are intended to be safe if implemented correctly, a full implementation is a massive undertaking and, as with any software, user agents are likely to have security bugs.
Even without scripting, there are specific features in HTML which, for historical
reasons,
are required for broad compatibility with legacy content but that expose the user to
unfortunate
security problems. In particular, the img element can be
used in
conjunction with
some other features as a way to effect a port scan from the user's location on the
Internet.
This can expose local network topologies that the attacker would otherwise not be able
to
determine.
HTML relies on a compartmentalization scheme sometimes known as the same-origin policy. An origin in most cases consists of all the pages served from the same host, on the same port, using the same protocol.
It is critical, therefore, to ensure that any untrusted content that forms part of a site be hosted on a different origin than any sensitive content on that site. Untrusted content can easily spoof any other page on the same origin, read data from that origin, cause scripts in that origin to execute, submit forms to and from that origin even if they are protected from cross-site request forgery attacks by unique tokens, and make use of any third-party resources exposed to or rights granted to that origin.
html" and "htm"
are commonly, but certainly not exclusively, used as the
extension for HTML documents.
TEXT
Fragments used with text/html resources
either refer to the indicated part of the corresponding
Document, or
provide state information for in-page scripts.
multipart/x-mixed-replace
This registration is for community review and will be submitted to the IESG for review, approval, and registration with IANA.
boundary (defined in RFC2046) [RFC2046]
multipart/x-mixed-replace
resource can be of any type, including types with non-trivial
security implications such as text/html.
multipart/mixed.
[RFC2046]
multipart/x-mixed-replace
resource.
Fragments
used with
multipart/x-mixed-replace
resources apply to each body part as defined by the type
used by that body part.
application/xhtml+xml
This registration is for community review and will be submitted to the IESG for review, approval, and registration with IANA.
application/xml
[RFC7303]
application/xml
[RFC7303]
application/xml
[RFC7303]
application/xml
[RFC7303]
application/xml
[RFC7303]
application/xhtml+xml
type asserts that the
resource is an XML document that likely has a document
element
from the HTML
namespace. Thus, the relevant specifications are XML, Namespaces
in
XML, and this specification. [XML] [XMLNS]
application/xml
[RFC7303]
application/xml
[RFC7303]
xhtml" and "xht" are sometimes used as
extensions for XML resources that have a document
element from the HTML
namespace.
TEXT
Fragments used with
application/xhtml+xml
resources have the same semantics as with any
XML MIME type. [RFC7303]
text/pingThis registration is for community review and will be submitted to the IESG for review, approval, and registration with IANA.
charset
The charset parameter may be provided. The parameter's value must be
"utf-8". This parameter serves no purpose; it is only allowed for
compatibility with legacy servers.
If used exclusively in the fashion described in the context of hyperlink auditing, this type introduces no new security concerns.
text/ping resources
always
consist of the
four
bytes 0x50 0x49 0x4E 0x47 (`PING`).
ping
attribute.
Fragments have no meaning with
text/ping resources.
application/microdata+json
This registration is for community review and will be submitted to the IESG for review, approval, and registration with IANA.
application/json
[JSON]
application/json
[JSON]
application/json
[JSON]
application/json
[JSON]
application/microdata+json
type asserts that the
resource is a JSON text that consists of an object with a single entry called
"items"
consisting of an array of entries, each of which consists of an object
with an entry called "id" whose value is a string, an entry called
"type"
whose
value is another string, and an entry called "properties" whose value is an
object
whose
entries each have a value consisting
of an array of either objects or strings, the objects being of the same form as the objects
in
the aforementioned "items" entry. Thus, the relevant specifications are
JSON and this specification. [JSON]
Applications that transfer data intended for use with HTML's microdata feature, especially in the context of drag-and-drop, are the primary application class for this type.
application/json
[JSON]
application/json
[JSON]
application/json
[JSON]
Fragments used with
application/microdata+json
resources have the same semantics as when used with
application/json
(namely, at the time of writing, no semantics at all).
[JSON]
text/event-streamThis registration is for community review and will be submitted to the IESG for review, approval, and registration with IANA.
charset
The charset parameter may be provided. The parameter's value must be
"utf-8". This parameter serves no purpose; it is only allowed for
compatibility with legacy servers.
An event stream from an origin distinct from the origin of the content consuming the event stream can result in information leakage. To avoid this, user agents are required to apply CORS semantics. [FETCH]
Event streams can overwhelm a user agent; a user agent is expected to apply suitable restrictions to avoid depleting local resources because of an overabundance of information from an event stream.
Servers can be overwhelmed if a situation develops in which the server is causing clients to reconnect rapidly. Servers should use a 5xx status code to indicate capacity problems, as this will prevent conforming clients from reconnecting automatically.
Fragments
have no meaning with
text/event-stream
resources.
web+ scheme prefixThis section describes a convention for use with the IANA URI scheme registry. It does not itself register a specific scheme. [RFC7595]
web+" followed by one or more
letters in the
range
a-z.
web+" schemes should use UTF-8 encodings where relevant.
web+" schemes. As
such, these schemes must not be used for features intended to be core platform features
(e.g.,
HTTP). Similarly, such schemes must not store confidential information in their URLs, such
as
usernames, passwords, personal information, or confidential project names.
The following sections only cover conforming elements and features.
This section is non-normative.
An asterisk (*) in a cell indicates that the actual rules are more complicated than indicated in the table above.
† Categories in the "Parents" column refer to parents that list
the given categories in their content model, not to elements that themselves are in those
categories. For example, the a
element's "Parents" column says "phrasing", so any
element whose content model contains the "phrasing" category could be a parent of an
a element. Since the
"flow"
category
includes all the "phrasing" elements, that means
the th element could
be a
parent to
an a element.
This section is non-normative.
This section is non-normative.
| Attribute | Element(s) | Description | Value |
|---|---|---|---|
abbr
| th
| Alternative label to use for the header cell when referencing the cell in other contexts | Text* |
accept
| input
| Hint for expected file type in file upload controls | Set of
comma-separated tokens* consisting of valid MIME type
strings with
no
parameters or audio/*, video/*, or
image/*
|
accept-charset
| form
| Character encodings to use for form submission | ASCII case-insensitive match for
"UTF-8"
|
accesskey
| HTML elements | Keyboard shortcut to activate or focus element | Ordered set of unique space-separated tokens, none of which are identical to another, each consisting of one code point in length |
action
| form
| URL to use for form submission | Valid non-empty URL potentially surrounded by spaces |
allow
| iframe
| Permissions policy to be applied
to the
iframe's
contents
| Serialized permissions policy |
allowfullscreen
| iframe
| Whether to allow the iframe's
contents to
use requestFullscreen()
| Boolean attribute |
alt
| area;
img;
input
| Replacement text for use when images are not available | Text* |
as
| link
| Potential destination for a
preload
request
(for rel="preload"
and
rel="modulepreload")
| Potential destination, for
rel="preload";
script-like destination, for
rel="modulepreload"
|
async
| script
| Execute script when available, without blocking while fetching | Boolean attribute |
autocapitalize
| HTML elements | Recommended autocapitalization behavior (for supported input methods) | "on";
"off";
"none";
"sentences";
"words";
"characters"
|
autocomplete
| form
| Default setting for autofill feature for controls in the form | "on"; "off"
|
autocomplete
| input;
select;
textarea
| Hint for form autofill feature | Autofill field name and related tokens* |
autofocus
| HTML elements | Automatically focus the element when the page is loaded | Boolean attribute |
autoplay
| audio;
video
| Hint that the media resource can be started automatically when the page is loaded | Boolean attribute |
blocking
| link;
script;
style
| Whether the element is potentially render-blocking | Unordered set of unique space-separated tokens* |
charset
| meta
| Character encoding declaration | "utf-8"
|
checked
| input
| Whether the control is checked | Boolean attribute |
cite
| blockquote;
del;
ins;
q
| Link to the source of the quotation or more information about the edit | Valid URL potentially surrounded by spaces |
class
| HTML elements | Classes to which the element belongs | Set of space-separated tokens |
color
| link
| Color to use when customizing a site's icon (for rel="mask-icon")
| CSS <color> |
cols
| textarea
| Maximum number of characters per line | Valid non-negative integer greater than zero |
colspan
| td;
th
| Number of columns that the cell is to span | Valid non-negative integer greater than zero |
content
| meta
| Value of the element | Text* |
contenteditable
| HTML elements | Whether the element is editable | "true"; "plaintext-only";
"false"
|
controls
| audio;
video
| Show user agent controls | Boolean attribute |
coords
| area
| Coordinates for the shape to be created in an image map | Valid list of floating-point numbers* |
crossorigin
| audio;
img;
link;
script;
video
| How the element handles crossorigin requests | "anonymous";
"use-credentials"
|
data
| object
| Address of the resource | Valid non-empty URL potentially surrounded by spaces |
datetime
| del;
ins
| Date and (optionally) time of the change | Valid date string with optional time |
datetime
| time
| Machine-readable value | Valid month string, valid date string, valid yearless date string, valid time string, valid local date and time string, valid time-zone offset string, valid global date and time string, valid week string, valid non-negative integer, or valid duration string |
decoding
| img
| Decoding hint to use when processing this image for presentation | "sync";
"async";
"auto"
|
default
| track
| Enable the track if no other text track is more suitable | Boolean attribute |
defer
| script
| Defer script execution | Boolean attribute |
dir
| HTML elements | The text directionality of the element | "ltr"; "rtl"; "auto"
|
dir
| bdo
| The text directionality of the element | "ltr"; "rtl"
|
dirname
| input;
textarea
| Name of form control to use for sending the element's directionality in form submission | Text* |
disabled
| button;
input;
optgroup;
option;
select;
textarea;
form-associated custom
elements
| Whether the form control is disabled | Boolean attribute |
disabled
| fieldset
| Whether the descendant form controls, except any inside legend,
are
disabled
| Boolean attribute |
disabled
| link
| Whether the link is disabled | Boolean attribute |
download
| a;
area
| Whether to download the resource instead of navigating to it, and its filename if so | Text |
draggable
| HTML elements | Whether the element is draggable | "true"; "false"
|
enctype
| form
| Entry list encoding type to use for form submission | "application/x-www-form-urlencoded";
"multipart/form-data";
"text/plain"
|
enterkeyhint
| HTML elements | Hint for selecting an enter key action | "enter";
"done";
"go";
"next";
"previous";
"search";
"send"
|
fetchpriority
| img;
link;
script
| Sets the priority for fetches initiated by the element | "auto";
"high";
"low"
|
for
| label
| Associate the label with form control | ID* |
for
| output
| Specifies controls from which the output was calculated | Unordered set of unique space-separated tokens consisting of IDs* |
form
| button;
fieldset;
input;
object;
output;
select;
textarea;
form-associated custom
elements
| Associates the element with a form
element
| ID* |
formaction
| button;
input
| URL to use for form submission | Valid non-empty URL potentially surrounded by spaces |
formenctype
| button;
input
| Entry list encoding type to use for form submission | "application/x-www-form-urlencoded";
"multipart/form-data";
"text/plain"
|
formmethod
| button;
input
| Variant to use for form submission | "GET";
"POST";
"dialog"
|
formnovalidate
| button;
input
| Bypass form control validation for form submission | Boolean attribute |
formtarget
| button;
input
| Navigable for form submission | Valid navigable target name or keyword |
headers
| td;
th
| The header cells for this cell | Unordered set of unique space-separated tokens consisting of IDs* |
height
| canvas;
embed;
iframe;
img;
input;
object;
source
(in picture);
video
| Vertical dimension | Valid non-negative integer |
hidden
| Whether the element is relevant | ""; ""; the empty string | |
high
| meter
| Low limit of high range | Valid floating-point number* |
href
| a;
area
| Address of the hyperlink | Valid URL potentially surrounded by spaces |
href
| link
| Address of the hyperlink | Valid non-empty URL potentially surrounded by spaces |
href
| base
| Document base URL | Valid URL potentially surrounded by spaces |
hreflang
| a;
link
| Language of the linked resource | Valid BCP 47 language tag |
http-equiv
| meta
| Pragma directive | "content-type";
"default-style";
"refresh";
"x-ua-compatible";
"content-security-policy"
|
id
| HTML elements | The element's ID | Text* |
imagesizes
| link
| Image sizes for different page layouts (for rel="preload")
| Valid source size list |
imagesrcset
| link
| Images to use in different situations, e.g., high-resolution displays, small
monitors, etc.
(for
rel="preload")
| Comma-separated list of image candidate strings |
inert
| HTML elements | Whether the element is inert. | Boolean attribute |
inputmode
| HTML elements | Hint for selecting an input modality | "none";
"text";
"tel";
"email";
"url";
"numeric";
"decimal";
"search"
|
integrity
| link;
script
| Integrity metadata used in Subresource Integrity checks [SRI] | Text |
is
| HTML elements | Creates a customized built-in element | Valid custom element name of a defined customized built-in element |
ismap
| img
| Whether the image is a server-side image map | Boolean attribute |
itemid
| HTML elements | Global identifier for a microdata item | Valid URL potentially surrounded by spaces |
itemprop
| HTML elements | Property names of a microdata item | Unordered set of unique space-separated tokens consisting of valid absolute URLs, defined property names, or text* |
itemref
| HTML elements | Referenced elements | Unordered set of unique space-separated tokens consisting of IDs* |
itemscope
| HTML elements | Introduces a microdata item | Boolean attribute |
itemtype
| HTML elements | Item types of a microdata item | Unordered set of unique space-separated tokens consisting of valid absolute URLs* |
kind
| track
| The type of text track | "subtitles";
"captions";
"descriptions";
"chapters";
"metadata"
|
label
| optgroup;
option;
track
| User-visible label | Text |
lang
| HTML elements | Language of the element | Valid BCP 47 language tag or the empty string |
list
| input
| List of autocomplete options | ID* |
loading
| iframe;
img
| Used when determining loading deferral | "lazy";
"eager"
|
loop
| audio;
video
| Whether to loop the media resource | Boolean attribute |
low
| meter
| High limit of low range | Valid floating-point number* |
max
| input
| Maximum value | Varies* |
max
| meter;
progress
| Upper bound of range | Valid floating-point number* |
maxlength
| input;
textarea
| Maximum length of value | Valid non-negative integer |
media
| link;
meta;
source;
style
| Applicable media | Valid media query list |
method
| form
| Variant to use for form submission | "GET";
"POST";
"dialog"
|
min
| input
| Minimum value | Varies* |
min
| meter
| Lower bound of range | Valid floating-point number* |
minlength
| input;
textarea
| Minimum length of value | Valid non-negative integer |
multiple
| input;
select
| Whether to allow multiple values | Boolean attribute |
muted
| audio;
video
| Whether to mute the media resource by default | Boolean attribute |
name
| button;
fieldset;
input;
output;
select;
textarea;
form-associated custom
elements
| Name of the element to use for form
submission and in the form.elements
API
| Text* |
name
| details
| Name of group of mutually-exclusive details
elements
| Text* |
name
| form
| Name of form to use in the document.forms
API
| Text* |
name
| iframe;
object
| Name of content navigable | Valid navigable target name or keyword |
name
| map
| Name of image map to reference from the usemap
attribute
| Text* |
name
| meta
| Metadata name | Text* |
name
| slot
| Name of shadow tree slot | Text |
nomodule
| script
| Prevents execution in user agents that support module scripts | Boolean attribute |
nonce
| HTML elements | Cryptographic nonce used in Content Security Policy checks [CSP] | Text |
novalidate
| form
| Bypass form control validation for form submission | Boolean attribute |
open
| details
| Whether the details are visible | Boolean attribute |
open
| dialog
| Whether the dialog box is showing | Boolean attribute |
optimum
| meter
| Optimum value in gauge | Valid floating-point number* |
pattern
| input
| Pattern to be matched by the form control's value | Regular expression matching the JavaScript Pattern production |
ping
| a;
area
| URLs to ping | Set of space-separated tokens consisting of valid non-empty URLs |
placeholder
| input;
textarea
| User-visible label to be placed within the form control | Text* |
playsinline
| video
| Encourage the user agent to display video content within the element's playback area | Boolean attribute |
popover
| HTML elements | Makes the element a popover element | "auto";
"manual";
|
popovertarget
| button;
input
| Targets a popover element to toggle, show, or hide | ID* |
popovertargetaction
| button;
input
| Indicates whether a targeted popover element is to be toggled, shown, or hidden | "toggle";
"show";
"hide"
|
poster
| video
| Poster frame to show prior to video playback | Valid non-empty URL potentially surrounded by spaces |
preload
| audio;
video
| Hints how much buffering the media resource will likely need | "none";
"metadata";
"auto"
|
readonly
| input;
textarea
| Whether to allow the value to be edited by the user | Boolean attribute |
readonly
| form-associated custom elements | Affects willValidate,
plus any behavior added by the custom element author
| Boolean attribute |
referrerpolicy
| a;
area;
iframe;
img;
link;
script
| Referrer policy for fetches initiated by the element | Referrer policy |
rel
| a;
area
| Relationship between the location in the document containing the hyperlink and the destination resource | Unordered set of unique space-separated tokens* |
rel
| link
| Relationship between the document containing the hyperlink and the destination resource | Unordered set of unique space-separated tokens* |
required
| input;
select;
textarea
| Whether the control is required for form submission | Boolean attribute |
reversed
| ol
| Number the list backwards | Boolean attribute |
rows
| textarea
| Number of lines to show | Valid non-negative integer greater than zero |
rowspan
| td;
th
| Number of rows that the cell is to span | Valid non-negative integer |
sandbox
| iframe
| Security rules for nested content | Unordered set
of unique
space-separated tokens, ASCII case-insensitive, consisting of
|
scope
| th
| Specifies which cells the header cell applies to | "row";
"col";
"rowgroup";
"colgroup"
|
selected
| option
| Whether the option is selected by default | Boolean attribute |
shadowrootclonable
| template
| Sets clonable on a declarative shadow root | Boolean attribute |
shadowrootdelegatesfocus
| template
| Sets delegates focus on a declarative shadow root | Boolean attribute |
shadowrootmode
| template
| Enables streaming declarative shadow roots | "open";
"closed"
|
shadowrootserializable
| template
| Sets serializable on a declarative shadow root | Boolean attribute |
shape
| area
| The kind of shape to be created in an image map | "circle";
"default";
"poly";
"rect"
|
size
| input;
select
| Size of the control | Valid non-negative integer greater than zero |
sizes
| link
| Sizes of the icons (for rel="icon")
| Unordered set of unique space-separated tokens, ASCII case-insensitive, consisting of sizes* |
sizes
| img;
source
| Image sizes for different page layouts | Valid source size list |
slot
| HTML elements | The element's desired slot | Text |
span
| col;
colgroup
| Number of columns spanned by the element | Valid non-negative integer greater than zero |
spellcheck
| HTML elements | Whether the element is to have its spelling and grammar checked | "true";
"false";
the empty string
|
src
| audio;
embed;
iframe;
img;
input;
script;
source (in
video
or audio);
track;
video
| Address of the resource | Valid non-empty URL potentially surrounded by spaces |
srcdoc
| iframe
| A document to render in the iframe
| The source of an
iframe srcdoc document*
|
srclang
| track
| Language of the text track | Valid BCP 47 language tag |
srcset
| img;
source
| Images to use in different situations, e.g., high-resolution displays, small monitors, etc. | Comma-separated list of image candidate strings |
start
| ol
| Starting value of the list | Valid integer |
step
| input
| Granularity to be matched by the form control's value | Valid
floating-point number greater than zero, or "any"
|
style
| HTML elements | Presentational and formatting instructions | CSS declarations* |
tabindex
| HTML elements | Whether the element is focusable and sequentially focusable, and the relative order of the element for the purposes of sequential focus navigation | Valid integer |
target
| a;
area
| Navigable for hyperlink navigation | Valid navigable target name or keyword |
target
| base
| Default navigable for hyperlink navigation and form submission | Valid navigable target name or keyword |
target
| form
| Navigable for form submission | Valid navigable target name or keyword |
title
| HTML elements | Advisory information for the element | Text |
title
| abbr;
dfn
| Full term or expansion of abbreviation | Text |
title
| input
| Description of pattern (when used with pattern
attribute)
| Text |
title
| link
| Title of the link | Text |
title
| link;
style
| CSS style sheet set name | Text |
translate
| HTML elements | Whether the element is to be translated when the page is localized | "yes"; "no"
|
type
| a;
link
| Hint for the type of the referenced resource | Valid MIME type string |
type
| button
| Type of button | "submit";
"reset";
"button"
|
type
| embed;
object;
source
| Type of embedded resource | Valid MIME type string |
type
| input
| Type of form control | input type
keyword
|
type
| ol
| Kind of list marker | "1";
"a";
"A";
"i";
"I"
|
type
| script
| Type of script | "module"; a valid MIME type string that is not a
JavaScript MIME type essence
match
|
usemap
| img
| Name of image map to use | Valid hash-name reference* |
value
| button;
option
| Value to be used for form submission | Text |
value
| data
| Machine-readable value | Text* |
value
| input
| Value of the form control | Varies* |
value
| li
| Ordinal value of the list item | Valid integer |
value
| meter;
progress
| Current value of the element | Valid floating-point number |
width
| canvas;
embed;
iframe;
img;
input;
object;
source (in
picture);
video
| Horizontal dimension | Valid non-negative integer |
wrap
| textarea
| How the value of the form control is to be wrapped for form submission | "soft";
"hard"
|
writingsuggestions
| HTML elements | Whether the element can offer writing suggestions or not. | "true";
"false";
the empty string
|
An asterisk (*) in a cell indicates that the actual rules are more complicated than indicated in the table above.
Support in all current engines.
Support in all current engines.
Support in all current engines.
Support in all current engines.
Support in all current engines.
Support in all current engines.
Support in all current engines.
This section is non-normative.
This section is non-normative.
AudioTrack
AudioTrackList
BarProp
BeforeUnloadEvent
BroadcastChannel
CanvasGradient
CanvasPattern
CanvasRenderingContext2D
CloseWatcher
CustomElementRegistry
CustomStateSet
DOMParser
DOMStringList
DOMStringMap
DataTransfer
DataTransferItem
DataTransferItemList
DedicatedWorkerGlobalScope
Document, partial
1 2
DragEvent
Element,
partial
ElementInternals
ErrorEvent
EventSource
External
FormDataEvent
HTMLAllCollection
HTMLAnchorElement,
partial
HTMLAreaElement,
partial
HTMLAudioElement
HTMLBRElement, partial
HTMLBaseElement
HTMLBodyElement,
partial
HTMLButtonElement
HTMLCanvasElement
HTMLDListElement,
partial
HTMLDataElement
HTMLDataListElement
HTMLDetailsElement
HTMLDialogElement
HTMLDirectoryElement
HTMLDivElement, partial
HTMLElement
HTMLEmbedElement,
partial
HTMLFieldSetElement
HTMLFontElement
HTMLFormControlsCollection
HTMLFormElement
HTMLFrameElement
HTMLFrameSetElement
HTMLHRElement, partial
HTMLHeadElement
HTMLHeadingElement,
partial
HTMLHtmlElement,
partial
HTMLIFrameElement,
partial
HTMLImageElement,
partial
HTMLInputElement,
partial
HTMLLIElement, partial
HTMLLabelElement
HTMLLegendElement,
partial
HTMLLinkElement,
partial
HTMLMapElement
HTMLMarqueeElement
HTMLMediaElement
HTMLMenuElement,
partial
HTMLMetaElement,
partial
HTMLMeterElement
HTMLModElement
HTMLOListElement,
partial
HTMLObjectElement,
partial
HTMLOptGroupElement
HTMLOptionElement
HTMLOptionsCollection
HTMLOutputElement
HTMLParagraphElement,
partial
HTMLParamElement
HTMLPictureElement
HTMLPreElement, partial
HTMLProgressElement
HTMLQuoteElement
HTMLScriptElement,
partial
HTMLSelectElement
HTMLSlotElement
HTMLSourceElement
HTMLSpanElement
HTMLStyleElement,
partial
HTMLTableCaptionElement,
partial
HTMLTableCellElement,
partial
HTMLTableColElement,
partial
HTMLTableElement,
partial
HTMLTableRowElement,
partial
HTMLTableSectionElement,
partial
HTMLTemplateElement
HTMLTextAreaElement
HTMLTimeElement
HTMLTitleElement
HTMLTrackElement
HTMLUListElement,
partial
HTMLUnknownElement
HTMLVideoElement
HashChangeEvent
History
ImageBitmap
ImageBitmapRenderingContext
ImageData
Location
MediaError
MessageChannel
MessageEvent
MessagePort
MimeType
MimeTypeArray
NavigateEvent
Navigation
NavigationActivation
NavigationCurrentEntryChangeEvent
NavigationDestination
NavigationHistoryEntry
NavigationTransition
Navigator, partial
NotRestoredReasonDetails
NotRestoredReasons
OffscreenCanvas
OffscreenCanvasRenderingContext2D
PageRevealEvent
PageSwapEvent
PageTransitionEvent
Path2D
Plugin
PluginArray
PopStateEvent
PromiseRejectionEvent
RadioNodeList
Range,
partial
ShadowRoot,
partial
SharedWorker
SharedWorkerGlobalScope
Storage
StorageEvent
SubmitEvent
TextMetrics
TextTrack
TextTrackCue
TextTrackCueList
TextTrackList
TimeRanges
ToggleEvent
TrackEvent
UserActivation
ValidityState
VideoTrack
VideoTrackList
VisibilityStateEntry
Window, partial
Worker
WorkerGlobalScope
WorkerLocation
WorkerNavigator
Worklet
WorkletGlobalScope
This section is non-normative.
The following table lists events fired by this document, excluding those already defined in media element events and drag-and-drop events.
| Event | Interface | Interesting targets | Description |
|---|---|---|---|
DOMContentLoaded
Support in all current engines. Firefox1+Safari3.1+Chrome1+
Opera9+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS?Chrome Android?WebView Android37+Samsung Internet?Opera Android10.1+ | Event
| Document
| Fired at the Document
once the
parser has
finished
|
afterprint
Support in all current engines. Firefox6+Safari13+Chrome63+
Opera?Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android? | Event
| Window
| Fired at the Window after
printing
|
beforeprint
Support in all current engines. Firefox6+Safari13+Chrome63+
Opera?Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android? | Event
| Window
| Fired at the Window before
printing
|
beforematch
Support in one engine only. FirefoxNoSafariNoChrome102+
OperaNoEdge102+ Edge (Legacy)?Internet ExplorerNo Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android? | Event
| Elements | Fired on elements with the attribute before they are revealed. |
beforetoggle
HTMLElement/beforetoggle_event Support in all current engines. Firefox🔰
114+Safaripreview+Chrome114+
Opera?Edge114+ Edge (Legacy)?Internet ExplorerNo Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android? | ToggleEvent
| Elements | Fired on elements with the popover
attribute when they
are transitioning between showing and hidden
|
beforeunload
Support in all current engines. Firefox1+Safari3+Chrome1+
Opera12+Edge79+ Edge (Legacy)12+Internet Explorer4+ Firefox Android?Safari iOS1+Chrome Android?WebView Android?Samsung Internet?Opera Android12+ | BeforeUnloadEvent
| Window
| Fired at the Window when the
page is
about to
be unloaded, in case the page would like to show a warning prompt
|
blur
| Event
| Window, elements
| Fired at nodes when they stop being focused |
cancel
HTMLDialogElement/cancel_event Support in all current engines. Firefox98+Safari15.4+Chrome37+
Opera?Edge79+ Edge (Legacy)?Internet ExplorerNo Firefox Android?Safari iOS?Chrome AndroidNoWebView Android?Samsung Internet?Opera Android? | Event
| CloseWatcher, dialog
elements,
input
elements
| Fired at CloseWatcher
objects or
dialog
elements when
they receive a close request,
or at
input
elements
in the File
state
when the user does not change their selection
|
change
Support in all current engines. Firefox1+Safari3+Chrome1+
Opera9+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android10.1+ | Event
| Form controls | Fired at controls when the user commits a value change (see also the input
event)
|
click
| PointerEvent
| Elements | Normally a mouse event; also synthetically fired at an element before its activation behavior is run, when an element is activated from a non-pointer input device (e.g. a keyboard) |
close
Support in all current engines. Firefox98+Safari15.4+Chrome37+
Opera?Edge79+ Edge (Legacy)?Internet ExplorerNo Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android? | Event
| CloseWatcher,
dialog
elements,
MessagePort
| Fired at CloseWatcher
objects or
dialog
elements when
they are closed via a close
request
or via
web developer code, or at MessagePort objects
when disentangled
|
connect
SharedWorkerGlobalScope/connect_event Support in all current engines. Firefox29+Safari16+Chrome4+
Opera10.6+Edge79+ Edge (Legacy)?Internet ExplorerNo Firefox Android?Safari iOS16+Chrome Android?WebView Android37+Samsung Internet?Opera Android11+ | MessageEvent
| SharedWorkerGlobalScope
| Fired at a shared worker's global scope when a new client connects |
contextlost
HTMLCanvasElement/webglcontextlost_event Support in one engine only. FirefoxNoSafariNoChrome98+
Opera?Edge98+ Edge (Legacy)?Internet ExplorerNo Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android? | Event
| canvas
elements, OffscreenCanvas
objects
| Fired when the corresponding CanvasRenderingContext2D
or OffscreenCanvasRenderingContext2D
is lost
|
contextrestored
HTMLCanvasElement/contextrestored_event Support in one engine only. FirefoxNoSafariNoChrome98+
Opera?Edge98+ Edge (Legacy)?Internet ExplorerNo Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android? | Event
| canvas
elements,
OffscreenCanvas
objects
| Fired when the corresponding CanvasRenderingContext2D
or OffscreenCanvasRenderingContext2D
is restored after being lost
|
currententrychange
| NavigationCurrentEntryChangeEvent
| Navigation
| Fired when navigation.currentEntry
changes
|
dispose
| Event
| NavigationHistoryEntry
| Fired when the session
history
entry corresponding to the NavigationHistoryEntry
has been permanently evicted from session history and can no longer be traversed to
|
error
Support in all current engines. Firefox6+Safari5+Chrome6+
Opera12+Edge79+ Edge (Legacy)?Internet ExplorerNo Firefox Android45+Safari iOS5+Chrome Android?WebView Android?Samsung Internet?Opera Android12+ Support in all current engines. Firefox6+Safari5.1+Chrome10+
Opera?Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS?Chrome Android?WebView Android37+Samsung Internet?Opera Android? | Event
or ErrorEvent
| Global scope objects, Worker
objects,
elements,
networking-related objects
| Fired when unexpected errors occur (e.g. networking errors, script errors, decoding errors) |
focus
| Event
| Window, elements
| Fired at nodes gaining focus |
formdata
HTMLFormElement/formdata_event Support in all current engines. Firefox72+Safari15+Chrome77+
Opera?Edge79+ Edge (Legacy)?Internet ExplorerNo Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android? | FormDataEvent
| form
elements
| Fired at a form
element
when it is constructing the entry list
|
hashchange
Support in all current engines. Firefox3.6+Safari5+Chrome8+
Opera10.6+Edge79+ Edge (Legacy)12+Internet Explorer8+ Firefox Android?Safari iOS5+Chrome Android?WebView Android37+Samsung Internet?Opera Android11+ | HashChangeEvent
| Window
| Fired at the Window when the
fragment part of the document's URL
changes
|
input
| Event
| Elements | Fired when the user changes the contenteditable
element's content, or the form control's value. See also the change event for form
controls.
|
invalid
HTMLInputElement/invalid_event Support in all current engines. Firefox4+Safari5+Chrome10+
Opera10+Edge79+ Edge (Legacy)12+Internet Explorer10+ Firefox Android64+Safari iOS5+Chrome Android?WebView Android4+Samsung Internet4.0+Opera Android12+ | Event
| Form controls | Fired at controls during form validation if they do not satisfy their constraints |
languagechange
Support in all current engines. Firefox32+Safari10.1+Chrome37+
Opera?Edge79+ Edge (Legacy)?Internet ExplorerNo Firefox Android4+Safari iOS?Chrome Android?WebView Android?Samsung Internet4.0+Opera Android? WorkerGlobalScope/languagechange_event Support in all current engines. Firefox74+Safari4+Chrome4+
Opera11.5+Edge79+ Edge (Legacy)?Internet ExplorerNo Firefox Android?Safari iOS5+Chrome Android?WebView Android37+Samsung Internet?Opera Android? | Event
| Global scope objects | Fired at the global scope object when the user's preferred languages change |
load
| Event
| Window, elements
| Fired at the Window when the
document has
finished loading; fired at an element containing a resource (e.g. img, embed) when
its
resource has
finished loading
|
message
BroadcastChannel/message_event Support in all current engines. Firefox38+Safari15.4+Chrome54+
Opera?Edge79+ Edge (Legacy)?Internet ExplorerNo Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android? DedicatedWorkerGlobalScope/message_event Support in all current engines. Firefox3.5+Safari4+Chrome4+
Opera10.6+Edge79+ Edge (Legacy)12+Internet Explorer10+ Firefox Android?Safari iOS5+Chrome Android?WebView Android37+Samsung Internet?Opera Android11.5+ Support in all current engines. Firefox6+Safari5+Chrome6+
Opera12+Edge79+ Edge (Legacy)?Internet ExplorerNo Firefox Android45+Safari iOS5+Chrome Android?WebView Android?Samsung Internet?Opera Android12+ Support in all current engines. Firefox41+Safari5+Chrome2+
Opera10.6+Edge79+ Edge (Legacy)12+Internet Explorer10+ Firefox Android?Safari iOS?Chrome Android?WebView Android37+Samsung Internet?Opera Android11.5+ Support in all current engines. Firefox9+Safari4+Chrome60+
Opera?Edge79+ Edge (Legacy)12+Internet Explorer8+ Firefox Android?Safari iOS4+Chrome Android?WebView Android?Samsung Internet?Opera Android47+ Support in all current engines. Firefox3.5+Safari4+Chrome4+
Opera10.6+Edge79+ Edge (Legacy)12+Internet Explorer10+ Firefox Android?Safari iOS5+Chrome Android?WebView Android?Samsung Internet?Opera Android11.5+ | MessageEvent
| Window, EventSource, MessagePort, BroadcastChannel,
DedicatedWorkerGlobalScope,
Worker, ServiceWorkerContainer
| Fired at an object when it receives a message |
messageerror
BroadcastChannel/messageerror_event Support in all current engines. Firefox57+Safari15.4+Chrome60+
Opera?Edge79+ Edge (Legacy)?Internet ExplorerNo Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android47+ DedicatedWorkerGlobalScope/messageerror_event Support in all current engines. Firefox57+Safari16.4+Chrome60+
Opera?Edge79+ Edge (Legacy)18Internet ExplorerNo Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android47+ MessagePort/messageerror_event Support in all current engines. Firefox57+Safari16.4+Chrome60+
Opera?Edge79+ Edge (Legacy)18Internet ExplorerNo Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android47+ Support in all current engines. Firefox57+Safari16.4+Chrome60+
Opera?Edge79+ Edge (Legacy)18Internet ExplorerNo Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android47+ Support in all current engines. Firefox57+Safari16.4+Chrome60+
Opera?Edge79+ Edge (Legacy)18Internet ExplorerNo Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android47+ | MessageEvent
| Window, MessagePort, BroadcastChannel,
DedicatedWorkerGlobalScope,
Worker, ServiceWorkerContainer
| Fired at an object when it receives a message that cannot be deserialized |
navigate
| NavigateEvent
| Navigation
| Fired before the navigable navigates, reloads, traverses, or otherwise changes its URL |
navigateerror
| ErrorEvent
| Navigation
| Fired when a navigation does not complete successfully |
navigatesuccess
| Event
| Navigation
| Fired when a navigation completes successfully |
offline
Support in all current engines. Firefox9+Safari4+Chrome3+
Opera?Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android? | Event
| Global scope objects | Fired at the global scope object when the network connections fails |
online
Support in all current engines. Firefox9+Safari4+Chrome3+
Opera?Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android? | Event
| Global scope objects | Fired at the global scope object when the network connections returns |
open
Support in all current engines. Firefox6+Safari5+Chrome6+
Opera12+Edge79+ Edge (Legacy)?Internet ExplorerNo Firefox Android45+Safari iOS5+Chrome Android?WebView Android?Samsung Internet?Opera Android12+ | Event
| EventSource
| Fired at EventSource
objects when a
connection is established
|
pageswap
| PageSwapEvent
| Window
| Fired at the Window right
before a
document
is unloaded as a result
of a
navigation.
|
pagehide
Support in all current engines. Firefox6+Safari5+Chrome3+
Opera?Edge79+ Edge (Legacy)12+Internet Explorer11 Firefox Android?Safari iOS?Chrome Android?WebView Android37+Samsung Internet?Opera Android? | PageTransitionEvent
| Window
| Fired at the Window when the
page's
session history
entry
stops
being the active
entry
|
pagereveal
| PageRevealEvent
| Window
| Fired at the Window when the
page
begins to
render for the first time after
it has been initialized or reactivated
|
pageshow
Support in all current engines. Firefox6+Safari5+Chrome3+
Opera?Edge79+ Edge (Legacy)12+Internet Explorer11 Firefox Android?Safari iOS?Chrome Android?WebView Android37+Samsung Internet?Opera Android? | PageTransitionEvent
| Window
| Fired at the Window when the
page's
session history
entry
becomes the active
entry
|
pointercancel
| PointerEvent
| Elements and Text
nodes
| Fired at the source node when the user attempts to initiate a drag-and-drop operation |
popstate
Support in all current engines. Firefox4+Safari5+Chrome5+
Opera11.5+Edge79+ Edge (Legacy)12+Internet Explorer10+ Firefox Android?Safari iOS?Chrome Android?WebView Android37+Samsung Internet?Opera Android11.5+ | PopStateEvent
| Window
| Fired at the Window when in
some
cases of session
history traversal
|
readystatechange
Document/readystatechange_event Support in all current engines. Firefox4+Safari5.1+Chrome9+
Opera12.1+Edge79+ Edge (Legacy)12+Internet Explorer4+ Firefox Android?Safari iOS?Chrome Android?WebView Android37+Samsung Internet?Opera Android12.1+ | Event
| Document
| Fired at the Document
when it
finishes
parsing and again when all its subresources have finished loading
|
rejectionhandled
| PromiseRejectionEvent
| Global scope objects | Fired at global scope objects when a previously-unhandled promise rejection becomes handled |
reset
Support in all current engines. Firefox6+Safari3+Chrome1+
Opera12.1+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS1+Chrome Android?WebView Android37+Samsung Internet?Opera Android12.1+ | Event
| form
elements
| Fired at a form
element
when it is reset
|
select
Support in all current engines. Firefox6+Safari1+Chrome1+
Opera12.1+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android12.1+ HTMLTextAreaElement/select_event Support in all current engines. Firefox6+Safari1+Chrome1+
Opera12.1+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android12.1+ | Event
| Form controls | Fired at form controls when their text selection is adjusted (whether by an API or by the user) |
storage
Support in all current engines. Firefox45+Safari4+Chrome1+
Opera?Edge79+ Edge (Legacy)15+Internet Explorer9+ Firefox Android?Safari iOS4+Chrome Android?WebView Android37+Samsung Internet?Opera Android? | StorageEvent
| Window
| Fired at Window event when
the
corresponding
localStorage
or
sessionStorage
storage
areas change
|
submit
Support in all current engines. Firefox1+Safari3+Chrome1+
Opera8+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS1+Chrome Android?WebView Android?Samsung Internet?Opera Android10.1+ | SubmitEvent
| form
elements
| Fired at a form
element
when it is submitted
|
toggle
HTMLDetailsElement/toggle_event Support in all current engines. Firefox49+Safari10.1+Chrome36+
Opera?Edge79+ Edge (Legacy)?Internet ExplorerNo Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android? Support in all current engines. Firefox🔰
114+Safaripreview+Chrome114+
Opera?Edge114+ Edge (Legacy)?Internet ExplorerNo Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android? | ToggleEvent
| details
and
popover elements
| Fired at details
elements when they open or close; fired on elements with the
popover attribute
when
they are
transitioning between
showing and hidden
|
unhandledrejection
Window/unhandledrejection_event Support in all current engines. Firefox69+Safari11+Chrome49+
Opera?Edge79+ Edge (Legacy)?Internet ExplorerNo Firefox Android?Safari iOS11.3+Chrome Android?WebView Android?Samsung Internet?Opera Android? | PromiseRejectionEvent
| Global scope objects | Fired at global scope objects when a promise rejection goes unhandled |
unload
Support in all current engines. Firefox1+Safari3+Chrome1+
Opera4+Edge79+ Edge (Legacy)12+Internet Explorer4+ Firefox Android?Safari iOS1+Chrome Android?WebView Android?Samsung Internet?Opera Android10.1+ | Event
| Window
| Fired at the Window object
when the
page is
going away
|
visibilitychange
Document/visibilitychange_event Support in all current engines. Firefox56+Safari14.1+Chrome62+
Opera49+Edge79+ Edge (Legacy)18Internet Explorer🔰 10+ Firefox Android?Safari iOS?Chrome Android?WebView Android62+Samsung Internet?Opera Android46+ | Event
| Document
| Fired at the Document
object when
the
page becomes visible or hidden to the
user
|
This section is non-normative.
The following HTTP request headers are defined by this specification:
Last-Event-ID`
Ping-From`
Ping-To`
The following HTTP response headers are defined by this specification:
Cross-Origin-Embedder-Policy`
Cross-Origin-Embedder-Policy-Report-Only`
Cross-Origin-Opener-Policy`
Cross-Origin-Opener-Policy-Report-Only`
Origin-Agent-Cluster`
Refresh`
X-Frame-Options`
This section is non-normative.
The following MIME types are mentioned in this specification:
application/atom+xml
application/json
application/octet-stream
application/microdata+json
application/rss+xml
application/x-www-form-urlencoded
application/xhtml+xml
application/xml
image/gif
image/jpeg
image/png
image/svg+xml
multipart/form-data
multipart/mixed
multipart/x-mixed-replace
text/css
text/event-stream
text/javascript
text/json
text/plain
text/html
text/ping
text/uri-list
text/vcard
text/vtt
text/xml
video/mp4
video/mpeg
All references are normative unless marked "Non-normative".
XMLHttpRequest, A. van
Kesteren.
WHATWG.
Thanks to Tim Berners-Lee for inventing HTML, without which none of this would exist.
Thanks to Aankhen, Aaqa Ishtyaq, Aaron Boodman, Aaron Leventhal, Aaron Krajeski, Abhishek Ghaskata, Abhishek Gupta, Adam Barth, Adam de Boor, Adam Hepton, Adam Klein, Adam Rice, Adam Roben, Addison Phillips, Adele Peterson, Adrian Bateman, Adrian Roselli, Adrian Sutton, Agustín Fernández, Aharon (Vladimir) Lanin, Ajai Tirumali, Ajay Poshak, Akatsuki Kitamura, Alan Plum, Alastair Campbell, Alejandro G. Castro, Alex Bishop, Alex Nicolaou, Alex Nozdriukhin, Alex Rousskov, Alex Soncodi, Alexander Farkas, Alexander J. Vincent, Alexander Kalenik, Alexandre Dieulot, Alexandre Morgaut, Alexey Feldgendler, Алексей Проскуряков (Alexey Proskuryakov), Alexey Shvayka, Alexis Deveria, Alfred Agrell, Ali Juma, Alice Boxhall, Alice Wonder, Allan Clements, Allen Wirfs-Brock, Alex Komoroske, Alex Russell, Alphan Chen, Aman Ansari, Ami Fischman, Amos Jeffries, Amos Lim, Anders Carlsson, André Bargull, André E. Veltstra, Andrea Rendine, Andreas, Andreas Deuschlinger, Andreas Farre, Andreas Kling, Andrei Popescu, Andres Gomez, Andres Rios, Andreu Botella, Andrew Barfield, Andrew Clover, Andrew Gove, Andrew Grieve, Andrew Kaster, Andrew Macpherson, Andrew Oakley, Andrew Paseltiner, Andrew Simons, Andrew Smith, Andrew W. Hagen, Andrew Williams, Andrey V. Lukyanov, Andry Rendy, Andy Davies, Andy Earnshaw, Andy Heydon, Andy Paicu, Andy Palay, Anjana Vakil, Ankur Kaushal, Anna Belle Leiserson, Anna Sidwell, Anthony Boyd, Anthony Bryan, Anthony Hickson, Anthony Ramine, Anthony Ricaud, Anton Vayvod, Antonio Sartori, Antti Koivisto, Arfat Salman, Arkadiusz Michalski, Arne Thomassen, Aron Spohr, Arphen Lin, Arthur Hemery, Arthur Sonzogni, Arthur Stolyar, Arun Patole, Aryeh Gregor, Asanka Herath, Asbjørn Ulsberg, Ashley Gullen, Ashley Sheridan, Asumu Takikawa, Atsushi Takayama, Attila Haraszti, Aurelien Levy, Ave Wrigley, Avi Drissman, Axel Dahmen, 방성범 (Bang Seongbeom), Barry Pollard, Ben Boyle, Ben Godfrey, Ben Golightly, Ben Kelly, Ben Lerner, Ben Leslie, Ben Meadowcroft, Ben Millard, Benjamin Carl Wiley Sittler, Benjamin Hawkes-Lewis, Benji Bilheimer, Benoit Ren, Bert Bos, Bijan Parsia, Bil Corry, Bill Mason, Bill McCoy, Billy Wong, Billy Woods, Bjartur Thorlacius, Björn Höhrmann, Blake Frantz, Bob Lund, Bob Owen, Bobby Holley, Boris Zbarsky, Brad Fults, Brad Neuberg, Brad Spencer, Bradley Meck, Brady Eidson, Brandon Jones, Brendan Eich, Brenton Simpson, Brett Wilson, Brett Zamir, Brian Birtles, Brian Blakely, Brian Campbell, Brian Korver, Brian Kuhn, Brian M. Dube, Brian Ryner, Brian Smith, Brian Wilson, Bryan Sullivan, Bruce Bailey, Bruce D'Arcus, Bruce Lawson, Bruce Miller, Bugs Nash, C. Scott Ananian, C. Williams, Cameron McCormack, Cameron Zemek, Cao Yipeng, Carlos Amengual, Carlos Gabriel Cardona, Carlos Ibarra López, Carlos Perelló Marín, Carolyn MacLeod, Casey Leask, Cătălin Badea, Cătălin Mariș, Cem Turesoy, ceving, Chao Cai, 윤석찬 (Channy Yun), Charl van Niekerk, Charlene Wright, Charles Iliya Krempeaux, Charles McCathie Nevile, Charlie Reis, 白丞祐 (Cheng-You Bai), Chris Apers, Chris Cressman, Chris Dumez, Chris Evans, Chris Harrelson, Chris Markiewicz, Chris Morris, Chris Nardi, Chris Needham, Chris Pearce, Chris Peterson, Chris Rebert, Chris Weber, Chris Wilson, Christian Biesinger, Christian Johansen, Christian Schmidt, Christoph Päper, Christophe Dumez, Christopher Aillon, Christopher Cameron, Christopher Ferris, Chriswa, Clark Buehler, Cole Robison, Colin Fine, Collin Jackson, Corey Farwell, Corprew Reed, Craig Cockburn, Csaba Gabor, Csaba Marton, Cynthia Shelly, Cyrille Tuzi, Daksh Shah, Dan Callahan, Dan Yoder, Dane Foster, Daniel Barclay, Daniel Bratell, Daniel Brooks, Daniel Brumbaugh Keeney, Daniel Buchner, Daniel Cheng, Daniel Clark, Daniel Davis, Daniel Ehrenberg, Daniel Glazman, Daniel Holbert, Daniel Peng, Daniel Schattenkirchner, Daniel Spång, Daniel Steinberg, Daniel Tan, Daniel Trebbien, Daniel Vogelheim, Danny Sullivan, Daphne Preston-Kendal, Darien Maillet Valentine, Darin Adler, Darin Fisher, Darxus, Dave Camp, Dave Cramer, Dave Hodder, Dave Lampton, Dave Singer, Dave Tapuska, Dave Townsend, David Baron, David Bloom, David Bokan, David Bruant, David Carlisle, David E. Cleary, David Egan Evans, David Fink, David Flanagan, David Gerard, David Grogan, David Hale, David Håsäther, David Hyatt, David I. Lehn, David John Burrowes, David Matja, David Remahl, David Resseguie, David Smith, David Storey, David Vest, David Woolley, David Zbarsky, Dave Methvin, DeWitt Clinton, Dean Edridge, Dean Edwards, Dean Jackson, Debanjana Sarkar, Debi Orton, Delan Azabani, Derek Featherstone, Derek Guenther, Devarshi Pant, Devdatta, Devin Mullins, Devin Rousso, Di Zhang, Diego Ferreiro Val, Diego González Zúñiga, Diego Ponce de León, Dimitri Glazkov, Dimitry Golubovsky, Dirk Pranke, Dirk Schulze, Dirkjan Ochtman, Divya Manian, Dmitry Lazutkin, Dmitry Titov, dolphinling, Dominic Cooney, Dominic Farolino, Dominique Hazaël-Massieux, Don Brutzman, Donovan Glover, Doron Rosenberg, Doug Kramer, Doug Simpkinson, Drew Wilson, Edgar Chen, Edmund Lai, Eduard Pascual, Eduardo Vela, Edward Welbourne, Edward Z. Yang, Ehsan Akhgari, Eira Monstad, Eitan Adler, Eli Friedman, Eli Grey, Eliot Graff, Elisabeth Robson, Elizabeth Castro, Elliott Sprehn, Elliotte Harold, Emilio Cobos Álvarez, Emily Stark, Eric Carlson, Eric Casler, Eric Lawrence, Eric Portis, Eric Rescorla, Eric Semling, Eric Shepherd, Eric Willigers, Erik Arvidsson, Erik Charlebois, Erik Rose, 栗本 英理子 (Eriko Kurimoto), espretto, Evan Jacobs, Evan Martin, Evan Prodromou, Evan Stade, Evert, Evgeny Kapun, ExE-Boss, Ezequiel Garzón, fantasai, Félix Sanz, Felix Sasaki, Fernando Altomare Serboncini, Forbes Lindesay, Francesco Schwarz, Francis Brosnan Blazquez, Franck 'Shift' Quélain, François Marier, Frank Barchard, Frank Liberato, Franklin Shirley, Frederik Braun, Fredrik Söderquist, 鵜飼文敏 (Fumitoshi Ukai), Futomi Hatano, Gavin Carothers, Gavin Kistner, Gareth Rees, Garrett Smith, Gary Blackwood, Gary Kacmarcik, Gary Katsevman, Geoff Richards, Geoffrey Garen, Georg Neis, George Lund, Gianmarco Armellin, Giovanni Campagna, Giuseppe Pascale, Glenn Adams, Glenn Maynard, Graham Klyne, Greg Botten, Greg Houston, Greg Wilkins, Gregg Tavares, Gregory J. Rosmaita, Gregory Terzian, Grey, Guilherme Johansson Tramontina, guest271314, Gytis Jakutonis, Håkon Wium Lie, Habib Virji, Hajime Morrita, Hallvord Reiar Michaelsen Steen, Hanna Laakso, Hans S. Tømmerhalt, Hans Stimer, Harald Alvestrand, Hayato Ito, 何志翔 (HE Zhixiang), Henri Sivonen, Henrik Lied, Henrik Lievonen, Henry Lewis, Henry Mason, Henry Story, Hermann Donfack Zeufack, 中川博貴 (Hiroki Nakagawa), Hiroshige Hayashizaki, Hiroyuki USHITO, Hitoshi Yoshida, Hongchan Choi, 王华 (Hua Wang), Hugh Bellamy, Hugh Guiney, Hugh Winkler, Ian Bicking, Ian Clelland, Ian Davis, Ian Fette, Ian Henderson, Ian Kilpatrick, Ibrahim Ahmed, Ido Green, Ignacio Javier, Igor Oliveira, 安次嶺 一功 (Ikko Ashimine), Ilya Grigorik, Ingvar Stepanyan, isonmad, Iurii Kucherov, Ivan Enderlin, Ivan Nikulin, Ivan Panchenko, Ivo Emanuel Gonçalves, J. King, J.C. Jones, Jackson Ray Hamilton, Jacob Davies, Jacques Distler, Jake Archibald, Jake Verbaten, Jakub Vrána, Jakub Łopuszański, Jakub Wilk, James Craig, James Graham, James Greene, James Justin Harrell, James Kozianski, James M Snell, James Perrett, James Robinson, Jamie Liu, Jamie Lokier, Jamie Mansfield, Jan Kühle, Jan Miksovsky, Janice Shiu, Janusz Majnert, Jan-Ivar Bruaroey, Jan-Klaas Kollhof, Jared Jacobs, Jason Duell, Jason Kersey, Jason Lustig, Jason Orendorff, Jason White, Jasper Bryant-Greene, Jasper St. Pierre, Jatinder Mann, Jay Henry Kao, Jean-Yves Avenard, Jed Hartman, Jeff Balogh, Jeff Cutsinger, Jeff Gilbert, Jeff "=JeffH" Hodges, Jeff Schiller, Jeff Walden, Jeffrey Yasskin, Jeffrey Zeldman, 胡慧鋒 (Jennifer Braithwaite), Jellybean Stonerfish, Jennifer Apacible, Jens Bannmann, Jens Fendler, Jens Oliver Meiert, Jens Widell, Jer Noble, Jeremey Hustman, Jeremy Keith, Jeremy Orlow, Jeremy Roman, Jeroen van der Meer, Jerry Smith, Jesse Renée Beach, Jessica Jong, jfkthame, Jian Li, Jihye Hong, Jim Jewett, Jim Ley, Jim Meehan, Jim Michaels, Jinho Bang, Jinjiang (勾三股四), Jirka Kosek, Jjgod Jiang, Joaquim Medeiros, João Eiras, Jochen Eisinger, Joe Clark, Joe Gregorio, Joel Spolsky, Joel Verhagen, Joey Arhar, Johan Herland, Johanna Herman, John Boyer, John Bussjaeger, John Carpenter, John Daggett, John Fallows, John Foliot, John Harding, John Keiser, John Law, John Musgrave, John Snyders, John Stockton, John-Mark Bell, Johnny Stenback, Jon Coppeard, Jon Ferraiolo, Jon Gibbins, Jon Jensen, Jon Perlow, Jonas Sicking, Jonathan Cook, Jonathan Kew, Jonathan Neal, Jonathan Oddy, Jonathan Rees, Jonathan Watt, Jonathan Worent, Jonny Axelsson, Joram Schrijver, Jordan Tucker, Jorgen Horstink, Joris van der Wel, Jorunn Danielsen Newth, Joseph Kesselman, Joseph Mansfield, Joseph Pecoraro, Josh Aas, Josh Hart, Josh Juran, Josh Levenberg, Josh Matthews, Joshua Bell, Joshua Chen, Joshua Randall, Juan Olvera, Juanmi Huertas, Jukka K. Korpela, Jules Clément-Ripoche, Julian Reschke, Julio Lopez, 小勝 純 (Jun Kokatsu), Jun Yang (harttle), Jungkee Song, Jürgen Jeka, Justin Lebar, Justin Novosad, Justin Rogers, Justin Schuh, Justin Sinclair, Juuso Lapinlampi, Ka-Sing Chou, Kagami Sascha Rosylight, Kai Hendry, Kamishetty Sreeja, 呂康豪 (KangHao Lu), Karl Dubost, Karl Tomlinson, Kartik Arora, Kartikaya Gupta, Kathy Walton, 河童エクマ(Kawarabe Ecma) Keith Cirkel, Keith Rollin, Keith Yeung, Kelly Ford, Kelly Norton, Ken Russell, Kenji Baheux, Kevin Benson, Kevin Cole, Kevin Gadd, Kevin Venkiteswaran, Khushal Sagar, Kinuko Yasuda, Koji Ishii, Kornél Pál, Kornel Lesinski, 上野 康平 (UENO, Kouhei), Kris Northfield, Kristof Zelechovski, Krzysztof Maczyński, 黒澤剛志 (Kurosawa Takeshi), Kyle Barnhart, Kyle Hofmann, Kyle Huey, Léonard Bouchet, Léonie Watson, Lachlan Hunt, Larry Masinter, Larry Page, Lars Gunther, Lars Solberg, Laura Carlson, Laura Granka, Laura L. Carlson, Laura Wisewell, Laurens Holst, Lawrence Forooghian, Lee Kowalkowski, Leif Halvard Silli, Leif Kornstaedt, Lenny Domnitser, Leonard Rosenthol, Leons Petrazickis, Liviu Tinta, Lobotom Dysmon, Logan, Logan Moore, Loune, Lucas Gadani, Łukasz Pilorz, Luke Kenneth Casson Leighton, Luke Warlow, Luke Wilde, Maciej Stachowiak, Magne Andersson, Magnus Kristiansen, Maik Merten, Majid Valipour, Malcolm Rowe, Manish Goregaokar, Manish Tripathi, Manuel Martinez-Almeida, Manuel Rego Casasnovas, Marc Hoyois, Marc-André Choquette, Marc-André Lafortune, Marco Zehe, Marcus Bointon, Marcus Otterström, Marijn Kruisselbrink, Mark Amery, Mark Birbeck, Mark Davis, Mark Green, Mark Miller, Mark Nottingham, Mark Pilgrim, Mark Rogers, Mark Rowe, Mark Schenk, Mark Vickers, Mark Wilton-Jones, Markus Cadonau, Markus Stange, Martijn van der Ven, Martijn Wargers, Martin Atkins, Martin Chaov, Martin Dürst, Martin Honnen, Martin Janecke, Martin Kutschker, Martin Nilsson, Martin Thomson, Masataka Yakura, Masatoshi Kimura, Mason Freed, Mason Mize, Mathias Bynens, Mathieu Henri, Matias Larsson, Matt Brubeck, Matt Di Pasquale, Matt Falkenhagen, Matt Giuca, Matt Harding, Matt Schmidt, Matt Wright, Matthew Gaudet, Matthew Gregan, Matthew Mastracci, Matthew Noorenberghe, Matthew Raymond, Matthew Thomas, Matthew Tylee Atkinson, Mattias Waldau, Max Romantschuk, Maxim Tsoy, Mayeul Cantan, Menachem Salomon, Menno van Slooten, Micah Dubinko, Micah Nerren, Michael 'Ratt' Iannarelli, Michael A. Nachbaur, Michael A. Puls II, Michael Carter, Michael Daskalov, Michael Day, Michael Dyck, Michael Enright, Michael Gratton, Michael Kohler, Michael McKelvey, Michael Nordman, Michael Powers, Michael Rakowski, Michael(tm) Smith, Michael Walmsley, Michal Zalewski, Michel Buffa, Michel Fortin, Michelangelo De Simone, Michiel van der Blonk, Miguel Casas-Sanchez, Mihai Şucan, Mihai Parparita, Mike Brown, Mike Dierken, Mike Dixon, Mike Hearn, Mike Pennisi, Mike Schinkel, Mike Shaver, Mikko Rantalainen, Mingye Wang, Mirko Brodesser, Mohamed Zergaoui, Mohammad Al Houssami, Mohammad Reza Zakerinasab, Momdo Nakamura, Morten Stenshorne, Mounir Lamouri, Ms2ger, mtrootyy, 邱慕安 (Mu-An Chiou), Mukilan Thiyagarajan, Mustaq Ahmed, Myles Borins, Nadia Heninger, Nate Chapin, NARUSE Yui, Navid Zolghadr, Neil Deakin, Neil Rashbrook, Neil Soiffer, Nereida Rondon, networkException, Nicholas Shanks, Nicholas Stimpson, Nicholas Zakas, Nickolay Ponomarev, Nicolas Gallagher, Nicolas Pena Moreno, Nicolò Ribaudo, Nidhi Jaju, Nikki Bee, Niklas Gögge, Nina Satragno, Noah Mendelsohn, Noah Slater, Noam Rosenthal, Noel Gordon, Nolan Waite, NoozNooz42, Norbert Lindenberg, Oisín Nolan, Ojan Vafai, Olaf Hoffmann, Olav Junker Kjær, Oldřich Vetešník, Oli Studholme, Oliver Hunt, Oliver Rigby, Olivia (Xiaoni) Lai, Olivier Gendrin, Olli Pettay, Ondřej Žára, Ori Avtalion, Oriol Brufau, oSand, Pablo Flouret, Patrick Dark, Patrick Garies, Patrick H. Lauke, Patrik Persson, Paul Adenot, Paul Lewis, Paul Norman, Per-Erik Brodin, 一丝 (percyley), Perry Smith, Peter Beverloo, Peter Karlsson, Peter Kasting, Peter Moulder, Peter Occil, Peter Stark, Peter Van der Beken, Peter van der Zee, Peter-Paul Koch, Phil Pickering, Philip Ahlberg, Philip Brembeck, Philip Taylor, Philip TAYLOR, Philippe De Ryck, Pierre-Arnaud Allumé, Pierre-Marie Dartus, Pierre-Yves Gérardy, Piers Wombwell, Pooja Sanklecha, Prashant Hiremath, Prashanth Chandra, Prateek Rungta, Pravir Gupta, Prayag Verma, 李普君 (Pujun Li), Rachid Finge, Rafael Weinstein, Rafał Miłecki, Rahul Purohit, Raj Doshi, Rajas Moonka, Rakina Zata Amni, Ralf Stoltze, Ralph Giles, Raphael Champeimont, Rebecca Star, Remci Mizkur, Remco, Remy Sharp, Rene Saarsoo, Rene Stach, Ric Hardacre, Rich Clark, Rich Doughty, Richa Rupela, Richard Gibson, Richard Ishida, Ricky Mondello, Rigo Wenning, Rikkert Koppes, Rimantas Liubertas, Riona Macnamara, Rob Buis, Rob Ennals, Rob Jellinghaus, Rob S, Rob Smith, Robert Blaut, Robert Collins, Robert Hogan, Robert Kieffer, Robert Linder, Robert Millan, Robert O'Callahan, Robert Sayre, Robin Berjon, Robin Schaufler, Rodger Combs, Roland Steiner, Roma Matusevich, Romain Deltour, Roman Ivanov, Roy Fielding, Rune Lillesveen, Russell Bicknell, Ruud Steltenpool, Ryan King, Ryan Landay, Ryan Sleevi, Ryo Kajiwara, Ryo Kato, Ryosuke Niwa, S. Mike Dierken, Salvatore Loreto, Sam Dutton, Sam Kuper, Sam Ruby, Sam Sneddon, Sam Weinig, Samikshya Chand, Samuel Bronson, Samy Kamkar, Sander van Lambalgen, Sanjoy Pal, Sanket Joshi, Sarah Gebauer, Sarven Capadisli, Satrujit Behera, Sayan Sivakumaran, Schalk Neethling, Scott Beardsley, Scott González, Scott Hess, Scott Miles, Scott O'Hara, Sean B. Palmer, Sean Feng, Sean Fraser, Sean Hayes, Sean Hogan, Sean Knapp, Sebastian Markbåge, Sebastian Schnitzenbaumer, Sendil Kumar N, Seth Call, Seth Dillingham, Shannon Moeller, Shanti Rao, Shaun Inman, Shiino Yuki, 贺师俊 (HE Shi-Jun), Shiki Okasaka, Shivani Sharma, shreyateeza, Shubheksha Jalan, Sidak Singh Aulakh, Sierk Bornemann, Sigbjørn Finne, Sigbjørn Vik, Silver Ghost, Silvia Pfeiffer, Šime Vidas, Simon Fraser, Simon Montagu, Simon Sapin, Yu Han, Simon Spiegel, Simon Wülker, skeww, Smylers, Srirama Chandra Sekhar Mogali, Stanton McCandlish, stasoid, Stefan Håkansson, Stefan Haustein, Stefan Santesson, Stefan Schumacher, Ştefan Vargyas, Stefan Weiss, Steffen Meschkat, Stephen Ma, Stephen Stewart, Stephen White, Steve Comstock, Steve Faulkner, Steve Fink, Steve Orvell, Steve Runyon, Steven Bennett, Steven Bingler, Steven Garrity, Steven Tate, Stewart Brodie, Stuart Ballard, Stuart Langridge, Stuart Parmenter, Subramanian Peruvemba, Sudhanshu Jaiswal, sudokus999, Sunava Dutta, Surma, Susan Borgrink, Susan Lesch, Sylvain Pasche, T.J. Crowder, Tab Atkins-Bittner, Taiju Tsuiki, Takashi Toyoshima, Takayoshi Kochi, Takeshi Yoshino, Tantek Çelik, 田村健人 (Kent TAMURA), Tawanda Moyo, Taylor Hunt, Ted Mielczarek, Terence Eden, Terrence Wood, Tetsuharu OHZEKI, Theresa O'Connor, Thijs van der Vossen, Thomas Broyer, Thomas Koetter, Thomas O'Connor, Tim Altman, Tim Dresser, Tim Johansson, Tim Nguyen, Tim Perry, Tim van der Lippe, TJ VanToll, Tobias Schneider, Tobie Langel, Toby Inkster, Todd Moody, Tom Baker, Tom Pike, Tom Schuster, Tom ten Thij, Tomasz Jakut, Tomek Wytrębowicz, Tommy Thorsen, Tony Ross, Tooru Fujisawa, Toru Kobayashi, Traian Captan, Travis Leithead, Trevor Rowbotham, Trevor Saunders, Trey Eckels, triple-underscore, Tristan Fraipont, 保呂 毅 (Tsuyoshi Horo), Tyler Close, Valentin Gosu, Vardhan Gupta, Vas Sudanagunta, Veli Şenol, Victor Carbune, Victor Costan, Vipul Snehadeep Chawathe, Vitya Muhachev, Vlad Levin, Vladimir Katardjiev, Vladimir Vukićević, Vyacheslav Aristov, voracity, Walter Steiner, Wakaba, Wayne Carr, Wayne Pollock, Wellington Fernando de Macedo, Weston Ruter, Wilhelm Joys Andersen, Will Levine, Will Ray, William Chen, William Swanson, Willy Martin Aguirre Rodriguez, Wladimir Palant, Wojciech Mach, Wolfram Kriesing, Xan Gregg, xenotheme, XhmikosR, Xida Chen, Xidorn Quan, Xue Fuqiao, Yang Chen, Yao Xiao, Yash Handa, Yay295, Ye-Kui Wang, Yehuda Katz, Yi Xu, Yi-An Huang, Yngve Nysaeter Pettersen, Yoav Weiss, Yonathan Randolph, Yu Huojiang, Yuki Okushi, Yury Delendik, 平野裕 (Yutaka Hirano), Yuzo Fujishima, 西條柚 (Yuzu Saijo), Zhenbin Xu, 张智强 (Zhiqiang Zhang), Zoltan Herczeg, Zyachel, and Øistein E. Andersen, for their useful comments, both large and small, that have led to changes to this specification over the years.
Thanks also to everyone who has ever posted about HTML to their blogs, public mailing lists, or forums, including all the contributors to the various W3C HTML WG lists and the various WHATWG lists.
Special thanks to Richard Williamson for creating the first implementation of
canvas in
Safari,
from which
the canvas feature was designed.
Special thanks also to the Microsoft employees who first implemented the event-based
drag-and-drop mechanism, contenteditable,
and other
features first widely deployed by the Windows Internet Explorer browser.
Special thanks and $10,000 to David Hyatt who came up with a broken implementation of the adoption agency algorithm that the editor had to reverse engineer and fix before using it in the parsing section.
Thanks to the participants of the microdata usability study for allowing us to use their mistakes as a guide for designing the microdata feature.
Thanks to the many sources that provided inspiration for the examples used in the specification.
Thanks also to the Microsoft blogging community for some ideas, to the attendees of the W3C Workshop on Web Applications and Compound Documents for inspiration, to the #mrt crew, the #mrt.no crew, and the #whatwg crew, and to Pillar and Hedral for their ideas and support.
Thanks to Igor Zhbanov for generating PDF versions of the specification.
Special thanks to the RICG for developing
the picture
element
and
related features; in particular thanks to Adrian Bateman,
Bruce Lawson, David Newton, Ilya Grigorik, John Schoenick, Leon de Rijke, Mat Marquis, Marcos
Cáceres, Tab Atkins, Theresa O'Connor, and Yoav Weiss for their contributions.
Special thanks to the WPWG for incubating the custom elements feature. In particular, thanks to David Hyatt and Ian Hickson for their influence through the XBL specifications, Dimitri Glazkov for the first draft of the custom elements specification, and to Alex Komoroske, Alex Russell, Andres Rios, Boris Zbarsky, Brian Kardell, Daniel Buchner, Dominic Cooney, Erik Arvidsson, Elliott Sprehn, Hajime Morrita, Hayato Ito, Jan Miksovsky, Jonas Sicking, Olli Pettay, Rafael Weinstein, Roland Steiner, Ryosuke Niwa, Scott Miles, Steve Faulkner, Steve Orvell, Tab Atkins, Theresa O'Connor, Tim Perry, and William Chen for their contributions.
Special thanks to the CSSWG for developing the worklets. In particular, thanks to Ian Kilpatrick for his work as editor of the original worklets specification.
For about ten years starting in 2003, this standard was almost entirely written by Ian Hickson (Google, ian@hixie.ch).
As of 2015, Simon Pieters (Mozilla, zcorpan@gmail.com), Anne van Kesteren (Apple, annevk@annevk.nl), Philip Jägenstedt (Google, philip@foolip.org), and Domenic Denicola (Google, d@domenic.me), all previously long-time contributors, have joined Ian in editing the text directly.
The image in the introduction is based on a photo by Wonderlane. (CC BY 2.0)
The image of the wolf in the embedded content introduction is based on a photo by Barry O'Neill. (Public domain)
The image of the kettlebell swing in the embedded content introduction is based on a photo by kokkarina. (CC0 1.0)
The Blue Robot Player sprite used in the canvas demo is based on a work by JohnColburn. (CC BY-SA 3.0)
The photograph of robot 148 climbing the tower at the FIRST Robotics Competition 2013 Silicon Valley Regional is based on a work by Lenore Edman. (CC BY 2.0)
The diagram showing how async
and defer impact script loading is based
on a
similar diagram from a
blog post by Peter Beverloo.
(CC0 1.0)
The image decoding demo used to demonstrate module-based workers draws on some example code from a tutorial by Ilmari Heikkinen. (CC BY 3.0)
The <flag-icon> example was inspired by a custom element by Steven
Skelton. (MIT)
Part of the revision history of the
picture element and
related
features
can be found in the ResponsiveImagesCG/picture-element
repository, which is available under the W3C Software
and
Document License.
Part of the revision history of the theme-color metadata name can
be found
in the
whatwg/meta-theme-color
repository, which is available under CC0.
Part of the revision history of the custom elements feature can be found in the w3c/webcomponents repository,
which
is available under the W3C Software
and
Document License.
Part of the revision history of the innerText getter and setter can be
found in
the rocallahan/innerText-spec
repository, which is available under CC0.
Part of the revision history of the worklets
feature can be found in the w3c/css-houdini-drafts
repository, which is available under the W3C Software
and
Document License.
Part of the revision history of the import
maps feature can be found in the WICG/import-maps
repository, which is available under the W3C Software
and
Document License.
Part of the revision history of the navigation API feature can be found in the WICG/navigation-api
repository, which is available under the W3C Software
and
Document License.
Part of the revision history of the Close requests and close watchers section can be
found in the WICG/close-watcher
repository, which is available under the W3C Software
and
Document License.
Copyright © WHATWG (Apple, Google, Mozilla, Microsoft). This work is licensed under a Creative Commons Attribution 4.0 International License. To the extent portions of it are incorporated into source code, such portions in the source code are licensed under the BSD 3-Clause License instead.
This is the Living Standard. Those interested in the patent-review version should view the Living Standard Review Draft.